Homelab MCP

Homelab MCP

A modular MCP (Model Context Protocol) server for homelab service management. Provides unified access to multiple homelab services through a single MCP interface.

Features

• Modular Architecture: Enable only the services you need
• Unified Health Checks: Monitor all services from one endpoint
• Docker Ready: Easy deployment to Unraid, Proxmox, or Kubernetes
• Extensible: Easy to add new service integrations

Supported Services

Quick Start

1. Clone and Configure

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

# Copy and edit configuration
cp config.example.yaml config.yaml
# Edit config.yaml with your service URLs and credentials

2. Run with Docker

docker compose up -d

3. Run Locally (Development)

# Install dependencies
pip install -e .

# Run server
python -m homelab_mcp.main

Configuration

Edit config.yaml to enable services and configure credentials:

server:
  host: "0.0.0.0"
  port: 6971
  transport: "streamable-http"

services:
  nginx_proxy_manager:
    enabled: true
    url: "http://192.168.1.100:81"
    username: "[email protected]"
    password: "your-password"

  pihole:
    enabled: true
    url: "http://192.168.1.53"
    api_key: "your-api-key"

  # ... more services

Available Tools

Core Tools

• homelab_health_check - Check health of all enabled services
• homelab_list_services - List configured services and status

Nginx Proxy Manager

• npm_list_proxy_hosts - List all proxy hosts
• npm_list_ssl_certificates - List SSL certificates
• npm_get_proxy_host - Get proxy host details
• npm_enable_proxy_host / npm_disable_proxy_host - Toggle hosts
• npm_check_expiring_certificates - Find expiring SSL certs

Pi-hole

• pihole_get_summary - DNS query statistics
• pihole_get_top_queries / pihole_get_top_blocked - Top domains
• pihole_enable / pihole_disable - Toggle ad blocking
• pihole_get_query_types - Query type breakdown

Uptime Kuma

• uptime_get_status_page - Get status page info
• uptime_get_heartbeats - Monitor heartbeat data
• uptime_get_monitor_summary - Summary of all monitors

Portainer

• portainer_list_endpoints - List Docker environments
• portainer_list_containers - List containers on endpoint
• portainer_get_endpoint_stats - Container/image/volume stats
• portainer_container_action - Start/stop/restart containers
• portainer_list_stacks - List docker-compose stacks

UPS NUT

• ups_get_status - Battery, load, runtime info
• ups_get_all_variables - All UPS variables
• ups_list_devices - List UPS devices
• ups_check_power_status - Quick power status check

Deployment

Docker Compose (Recommended)

docker compose up -d

Unraid

1. Copy files to /mnt/user/appdata/homelab-mcp/
2. Build and run:

docker build -t homelab-mcp .
docker run -d --name homelab-mcp \
  -p 6971:6971 \
  -v /mnt/user/appdata/homelab-mcp/config.yaml:/app/config.yaml:ro \
  homelab-mcp

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: homelab-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: homelab-mcp
  template:
    metadata:
      labels:
        app: homelab-mcp
    spec:
      containers:
      - name: homelab-mcp
        image: homelab-mcp:latest
        ports:
        - containerPort: 6971
        volumeMounts:
        - name: config
          mountPath: /app/config.yaml
          subPath: config.yaml
      volumes:
      - name: config
        configMap:
          name: homelab-mcp-config

Adding New Services

1. Create a new directory under homelab_mcp/services/
2. Implement ServiceBase class with:
   • _create_client() - HTTP client setup
   • register_tools() - MCP tool registration
   • health_check() - Service health check
3. Add configuration model to core/config.py
4. Register in server.py

MCP Client Configuration

Add to your MCP client (e.g., Windsurf):

{
  "mcpServers": {
    "homelab": {
      "serverType": "streamable-http",
      "url": "http://192.168.1.100:6971/mcp"
    }
  }
}

License

MIT