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

Service	Description	Status
Nginx Proxy Manager	Reverse proxy management, SSL certificates	✅ Ready
Pi-hole	DNS ad-blocking, query stats	✅ Ready
Uptime Kuma	Service availability monitoring	✅ Ready
Portainer	Docker management across hosts	✅ Ready
UPS NUT	UPS power monitoring	✅ Ready

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: "admin@example.com" 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

Copy files to /mnt/user/appdata/homelab-mcp/
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

Create a new directory under homelab_mcp/services/
Implement ServiceBase class with:
- _create_client() - HTTP client setup
- register_tools() - MCP tool registration
- health_check() - Service health check
Add configuration model to core/config.py
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

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Homelab MCP

Homelab MCP

Features

Supported Services

Quick Start

1. Clone and Configure

2. Run with Docker

3. Run Locally (Development)

Configuration

Available Tools

Core Tools

Nginx Proxy Manager

Pi-hole

Uptime Kuma

Portainer

UPS NUT

Deployment

Docker Compose (Recommended)

Unraid

Kubernetes

Adding New Services

MCP Client Configuration

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API