# 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
```bash
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
```bash
docker compose up -d
```
### 3. Run Locally (Development)
```bash
# Install dependencies
pip install -e .
# Run server
python -m homelab_mcp.main
```
## Configuration
Edit `config.yaml` to enable services and configure credentials:
```yaml
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)
```bash
docker compose up -d
```
### Unraid
1. Copy files to `/mnt/user/appdata/homelab-mcp/`
2. Build and run:
```bash
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
```yaml
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):
```json
{
"mcpServers": {
"homelab": {
"serverType": "streamable-http",
"url": "http://192.168.1.100:6971/mcp"
}
}
}
```
## License
MIT