Labsco
MCP SERVER

Homelab MCP

by bjeans ↗

Query your homelab from Claude Desktop — Docker and Podman hosts, Ansible inventory, Ollama and LiteLLM, Pi-hole, Unifi and UPS power — with your real hostnames offered as dropdowns.

Containers, Kubernetes & Cluster Operations
Summary
Inventory-driven enums are the difference between usable and guesswork.

Without an inventory the tools still work, but you are typing hostnames from memory; with `ANSIBLE_INVENTORY_PATH` set, your real groups appear as choices and a wrong guess stops being a failure mode. The MCP Registry Inspector server is deprecated as of v2.3.0 and slated for removal in v3.0.0, since clients can now read those files directly — leave it out of new configurations.

What it is

A set of MCP servers for homelab infrastructure, shipped either as one unified process with namespaced tools or as seven individual servers. It reads container state across hosts, resolves hosts and groups from your Ansible inventory, checks Ollama and LiteLLM, reports Pi-hole DNS statistics, lists Unifi network devices and clients, and monitors UPS power through NUT. Point it at an inventory file and the tool parameters are populated with your actual group and host names instead of free-text fields.

What you get
  • Containers across every configured Docker or Podman host: full listings, per-container stats, existence checks and label-based lookups — `docker_get_containers`, `docker_get_all_containers`, `docker_get_container_stats`, `docker_check_container`, `docker_find_containers_by_label`, `docker_get_container_labels`
  • Your Ansible inventory as a queryable graph: hosts, groups, host details, group membership, search and a summary, with a reload that avoids restarting — `ansible_get_all_hosts`, `ansible_get_all_groups`, `ansible_get_host_details`, `ansible_get_group_details`, `ansible_get_hosts_by_group`, `ansible_search_hosts`, `ansible_get_inventory_summary`, `ansible_reload_inventory`
  • Reachability checks against one host, a group, or everything in the inventory — `ping_host`, `ping_group`, `ping_all`, `list_groups`
  • Local model infrastructure: which Ollama instances are up, what models they hold, and whether the LiteLLM proxy is healthy — `get_ollama_status`, `get_ollama_models`, `get_litellm_status`
  • Pi-hole DNS statistics and status, and Unifi devices, clients and a network summary — `get_pihole_stats`, `get_pihole_status`, `get_network_devices`, `get_network_clients`, `get_network_summary`, `refresh_network_data`
  • UPS power state through NUT: status, details, remaining battery runtime and recent power events across the UPS devices you have — `get_ups_status`, `get_ups_details`, `get_battery_runtime`, `get_power_events`, `list_ups_devices`
Requirements

Python 3.10 or newer for the native install, or the published image `bjeans/homelab-mcp` — the Docker path is the one the README recommends for production. Credentials for each service go in a `.env` file the README asks you to keep out of version control, with a separate API key per service. `ANSIBLE_INVENTORY_PATH` points at your inventory and is what turns tool parameters into dropdowns; the enums are built once at startup, so changing the inventory means restarting the client. Unified mode runs all seven servers in one process with namespaced tool names; setting `ENABLED_SERVERS` selects individual ones instead. FastMCP gives it stdio by default plus HTTP and SSE transports. The README is blunt that Docker and Podman APIs are typically unauthenticated HTTP and must never be reachable from the internet — restrict them with firewall rules first.

Setup effort

One command plus a key — docker pull bjeans/homelab-mcp:latest, then supply credentials