Homelab MCP

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

Tools you get

33 tools named in the project's documentation.

Requires

• docker on PATH
• Python 3.10+
• PIHOLE_API_KEY_SERVER1 in your environment
• UNIFI_API_KEY in your environment

Where it runs

The documented client runs the server on your machine.