🏠 Homelab MCP Server

A unified Model Context Protocol (MCP) server that connects AI agents to your self-hosted homelab infrastructure.

Expose 9 homelab services through a single MCP endpoint for AI assistants (Claude, Gemini, ChatGPT, Cursor, etc.) and a full REST API for automation tools like n8n.

✨ Features

30 consolidated MCP tools – action-based compound tools that keep context windows efficient
MCP Resources – real-time data feeds (clients, devices, queues, health) that agents can subscribe to
MCP Prompts – pre-built prompt templates for common tasks (troubleshooting, security audits, health checks)
Full REST API – every tool is also exposed as a REST endpoint with Swagger docs
Conditional registration – only enabled services register their tools, keeping the tool list clean
Docker-first deployment – single docker compose up to run everything
Structured error handling – consistent JSON errors with proper HTTP status codes
Audit logging – every tool call is traced and logged

📦 Supported Services

| Service | Category | MCP Tools | Capabilities | |---------|----------|-----------|--------------| | Unifi | Networking | 9 | Clients, devices, firewall, VLANs, security, guest access, backups | | Proxmox | Virtualization | 3 | VMs, containers, snapshots, storage, power management | | Plex | Media Server | 2 | Playback activity, library search, scans, stream control | | Radarr / Sonarr | Media Management | 4 | Movie & TV search, add content, calendar, download queue | | SABnzbd | Downloads | 2 | Queue management, speed limits, history | | Portainer | Docker | 4 | Containers, stacks, volumes, logs across environments | | OPNsense | Firewall | 2 | Interfaces, DHCP, gateway, firmware, service management | | Home Assistant | IoT / Smart Home | 3 | Entities, automations, scenes, service calls, history | | Traefik | Reverse Proxy | 1 | Router inspection, service backends, health overview |

🚀 Quick Start

Prerequisites

Docker and Docker Compose (recommended)
or Python 3.11+ for local development

1. Clone the repository

git clone https://github.com/theonlytruebigmac/homelab-mcp.git
cd homelab-mcp

2. Configure your environment

cp .env.example .env

Edit .env and configure the services you want to use. Each service has an *_ENABLED flag — set any service to false to disable it entirely (its tools and routes won't be registered):

# ---- MCP Server ----
MCP_HOST=0.0.0.0
MCP_PORT=3333

# ---- Logging ----
LOG_LEVEL=INFO            # DEBUG, INFO, WARNING, ERROR
LOG_JSON_FORMAT=false     # true for structured JSON logs

# ---- Unifi Controller ----
UNIFI_ENABLED=true
UNIFI_URL=https://192.168.1.1:8443
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your_password_here
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

# ---- Radarr (Movies) ----
RADARR_ENABLED=true
RADARR_URL=http://your-radarr-ip:7878
RADARR_API_KEY=your_radarr_api_key_here

# ---- Sonarr (TV) ----
SONARR_ENABLED=true
SONARR_URL=http://your-sonarr-ip:8989
SONARR_API_KEY=your_sonarr_api_key_here

# ---- Plex ----
PLEX_ENABLED=true
PLEX_URL=http://your-plex-ip:32400
PLEX_TOKEN=your_plex_token_here

# ---- Proxmox ----
PROXMOX_ENABLED=true
PROXMOX_URL=https://your-proxmox-ip:8006
PROXMOX_USER=root@pam
PROXMOX_PASSWORD=your_password_here

# ---- Portainer ----
PORTAINER_ENABLED=true
PORTAINER_URL=http://your-portainer-ip:9000
PORTAINER_ACCESS_TOKEN=your_access_token_here

# ---- OPNsense ----
OPNSENSE_ENABLED=true
OPNSENSE_URL=https://your-opnsense-ip
OPNSENSE_API_KEY=your_api_key
OPNSENSE_API_SECRET=your_api_secret

# ---- Home Assistant ----
HASS_ENABLED=true
HASS_URL=http://homeassistant.local:8123
HASS_TOKEN=your_long_lived_access_token

# ---- SABnzbd ----
SABNZBD_ENABLED=true
SABNZBD_URL=http://localhost:8080
SABNZBD_API_KEY=your_api_key

# ---- Traefik ----
TRAEFIK_ENABLED=true
TRAEFIK_URL=http://localhost:8080
TRAEFIK_USERNAME=            # optional basic auth
TRAEFIK_PASSWORD=

Tip: You only need to configure the services you actually use. Set *_ENABLED=false for everything else — those tools won't even appear in the MCP tool list.

3. Deploy with Docker Compose

docker compose up -d --build

The server will be available at:

| Endpoint | URL | Description | |----------|-----|-------------| | MCP | http://localhost:3333/mcp | Connect your AI agent here | | REST API Docs | http://localhost:3333/docs | Interactive Swagger UI | | Health Check | http://localhost:3333/health | Server status + version | | Unified Status | http://localhost:3333/api/status | Health of all services |

4. Connect your AI agent

Claude Desktop / Cursor / Gemini CLI — add to your MCP config:

{
  "mcpServers": {
    "homelab-mcp": {
      "url": "http://<your-server-ip>:3333/mcp"
    }
  }
}

🛠️ Local Development (without Docker)

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install the package in development mode
pip install -e ".[dev]"

# Configure environment
cp .env.example .env
# Edit .env with your service credentials

# Run the server
homelab-mcp

The homelab-mcp entry point is defined in pyproject.toml and runs src/homelab_mcp/server.py:main().

🏗️ Architecture

src/homelab_mcp/
├── server.py            # FastMCP + FastAPI app, tool/router registration, lifespan
├── config.py            # Pydantic Settings for all services
├── services/
│   ├── unifi/           # Unifi Controller integration
│   │   ├── client.py    # API client (aiohttp)
│   │   └── tools.py     # MCP tools + impl functions
│   ├── proxmox/         # Proxmox VE integration
│   ├── plex/            # Plex Media Server
│   ├── media/           # Radarr + Sonarr
│   ├── portainer/       # Docker via Portainer
│   ├── opnsense/        # OPNsense firewall
│   ├── hass/            # Home Assistant
│   ├── sabnzbd/         # SABnzbd Usenet
│   └── traefik/         # Traefik reverse proxy
├── routers/             # FastAPI REST routers (one per service)
└── utils/
    ├── logging.py       # @traced decorator, audit trail
    └── exceptions.py    # Structured error hierarchy

Each service follows the same pattern:

client.py — async API client using aiohttp with lazy initialization
tools.py — _impl functions shared by both MCP tools and REST routers, plus register_*_tools() to register consolidated MCP tools, resources, and prompts

📡 n8n Integration

This server provides a REST API designed for n8n workflow automation:

AI Agent Node — Use the built-in MCP tool support or the "Call Workflow" pattern
HTTP Request Node — Call any REST endpoint directly (see Swagger at /docs)
Subworkflow — Route tool calls to REST endpoints for complex automation chains

📚 Documentation

| Document | Description | |----------|-------------| | MCP Tool Reference | All tools available to AI agents | | REST API Reference | Full endpoint listing for automation | | Swagger UI | Interactive API explorer (when running) |

📄 License

This project is licensed under the MIT License.

MCP Servers