home / mcp / homelab mcp server

Homelab MCP Server

Model Context Protocol (MCP) servers for managing homelab infrastructure through Claude Desktop. Monitor Docker/Podman containers, Ollama AI models, Pi-hole DNS, Unifi networks, and Ansible inventory. Includes security checks, templates, and automated pre-push validation. Production-ready for homelabs.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "bjeans-homelab-mcp": {
      "command": "python",
      "args": [
        "C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"
      ],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    }
  }
}

You run Model Context Protocol (MCP) servers to manage and monitor your homelab infrastructure from Claude Desktop. These MCP servers expose practical tools that query, monitor, and control your network services, containers, monitoring controllers, and power infrastructure in a secure, centralized way. You can choose a unified server that runs all MCP servers in one process or run each server separately, depending on your environment and preferences.

How to use

You access MCP through your Claude Desktop project by loading the MCP server configuration you choose. Use the unified server for a streamlined setup where all tools are available from one Python process, or run individual servers to keep them isolated and easier to manage. Tools in the unified mode are namespaced, for example docker_get_containers and ping_ping_host, while individual servers retain their specific tool names like get_docker_containers or ping_host.

How to install

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
    }
  }
}

Prerequisites: - Python 3.10+ installed on the host - Claude Desktop installed and configured - Access to the MCP server code and the path in your environment Then you can start the unified MCP server using the command shown above. If you prefer running each server separately, you can use the individual server configuration below.

Deployment options and configuration details

Deployment offers two modes and two methods: unified server mode (recommended, especially for Docker deployments) and individual server mode (legacy but fully supported). Both modes provide a path to running the MCP servers either via Docker or native Python installations.

{
  "mcpServers": {
    "docker": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"]
    },
    "ollama": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"]
    }
  }
}

Environment and security notes

Keep your environment secure by using unique API keys, restricting network access, and keeping sensitive files private. The setup includes an Ansible inventory path option to define your infrastructure centrally, and you may pass this as an environment variable in the unified or individual server configurations.

Notes on transport and startup

The MCP framework supports multiple transports. The standard setup uses stdio (the default for Claude Desktop). HTTP and SSE transports are available for remote or streaming scenarios, but require starting the servers with the appropriate transport flags and host/port settings.

Troubleshooting and common issues

If Claude Desktop has trouble loading MCP servers, verify the config entry matches the server you start, confirm the Python path is correct, and restart Claude Desktop. Review logs for error messages and ensure environment variables are loaded correctly.

Examples and quick-start snippets

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
    }
  }
}

Available tools

docker_get_containers

Get containers on a specific host in unified mode (namespaced under docker) or in standalone mode for per-host access.

docker_get_all_containers

Retrieve all containers across all hosts managed by the MCP Docker server.

docker_get_container_stats

Fetch CPU and memory statistics for a specific container across the managed hosts.

docker_check_container

Verify whether a given container is running on a specified host.

docker_find_containers_by_label

Search for containers by label across the fleet.

docker_get_container_labels

List all labels for a specific container.

ping_host

Ping a single host resolved from the Ansible inventory to verify reachability.

ping_group

Ping all hosts within an Ansible inventory group concurrently.

ping_all

Ping all infrastructure hosts concurrently for quick health checks.

get_pihole_stats

Collect DNS statistics from all Pi-hole instances.

get_pihole_status

Check which Pi-hole instances are online.

get_network_devices

List all Unifi network devices (switches, APs, gateways) known to the controller.

get_network_clients

List active clients seen by the Unifi controller.

get_network_summary

Provide a quick overview of the Unifi network status.

refresh_network_data

Force a refresh of network data from the Unifi controller, bypassing cache.

get_ollama_status

Check status of all Ollama instances and their model counts.

get_ollama_models

Obtain the detailed model list for a specific Ollama host.

get_litellm_status

Verify that the LiteLLM proxy is online and responding.

get_inventory_summary

Provide a high-level summary of the Ansible inventory.

reload_inventory

Reload the Ansible inventory from disk.

ansible_get_all_hosts

Return all hosts in the Ansible inventory (unified mode).

ansible_get_all_groups

Return all groups in the Ansible inventory (unified mode).

ansible_get_host_details

Return detailed information for a specific host in the inventory.

ansible_get_group_details

Return detailed information for a specific group in the inventory.

ansible_search_hosts

Search hosts by pattern or variable within the inventory.

ansible_reload_inventory

Reload the inventory from disk in unified mode.