https://github.com/mtgibbs/pi-cluster-mcp
Connect Claude to your homelab safely. This MCP server provides structured tools for K3s cluster operations, Pi-hole DNS management, and Jellyfin/Immich control, built with a security-first architecture.
https://github.com/mtgibbs/pi-cluster-mcp
homelab-automation mcp mcp-server model-context-protocol raspberry-pi
Last synced: 5 months ago
JSON representation
Connect Claude to your homelab safely. This MCP server provides structured tools for K3s cluster operations, Pi-hole DNS management, and Jellyfin/Immich control, built with a security-first architecture.
- Host: GitHub
- URL: https://github.com/mtgibbs/pi-cluster-mcp
- Owner: mtgibbs
- Created: 2026-01-26T17:10:26.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-29T05:30:14.000Z (5 months ago)
- Last Synced: 2026-01-29T16:10:08.600Z (5 months ago)
- Topics: homelab-automation, mcp, mcp-server, model-context-protocol, raspberry-pi
- Language: TypeScript
- Homepage:
- Size: 313 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Homelab MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server designed for managing a Kubernetes-based homelab (specifically a Raspberry Pi K3s cluster).
This server provides a safe, structured interface for LLMs (like Claude) to interact with your cluster, media services, and network infrastructure without giving them raw `kubectl` access or unrestricted SSH capabilities.
## 🚀 Features
### Kubernetes Operations
- **Health Checks:** Monitor nodes, resource usage, and problem pods.
- **Resource Inspection:** List and describe deployments, statefulsets, daemonsets, pods, services, and configmaps with full spec details.
- **Storage:** Inspect PersistentVolumeClaims with status, capacity, and storage class info.
- **Safe Restarts:** Trigger rolling restarts for whitelisted deployments (e.g., Jellyfin, Pi-hole, media stack).
- **Backups:** Check CronJob status, inspect detailed job specs, retrieve job pod logs, and manually trigger backup jobs.
- **GitOps:** Monitor Flux Kustomizations/HelmReleases and trigger reconciliation.
- **Secrets:** View External Secrets sync status and force refreshes (1Password integration).
### Network & DNS (Pi-hole/Unbound)
- **Status:** Check health of DNS services.
- **Diagnostics:** View blocked query stats, top blocked domains, and recent query logs.
- **Testing:** Run `dig` commands from within the cluster to verify resolution.
- **Management:** View whitelist and trigger Gravity updates.
### Media Services (Jellyfin/Immich)
- **Health:** Monitor pod status for media applications.
- **Stats:** detailed library statistics and active session monitoring.
- **Management:** Search media libraries and trigger metadata refreshes for specific items.
### Network Diagnostics
- **Node Networking:** Inspect interfaces, addresses, routes, and routing rules on any cluster node.
- **Firewall Rules:** Dump iptables/ip6tables rules by table and chain.
- **Connection Tracking:** View conntrack entries with source/destination filtering.
- **Ingress Testing:** Curl ingress URLs from within the cluster with detailed timing.
- **Connectivity Testing:** Ping and TCP port checks between nodes and targets.
- **Pod Logs:** Retrieve pod logs with container, time range, and line count filtering.
### Infrastructure
- **Certificates:** Monitor cert-manager certificate expiry and readiness.
- **NAS Integration:** Securely touch specific paths on a Synology NAS (via SSH) to trigger file system events.
- **Tailscale:** Monitor VPN connector status.
## 🔒 Security Model
This project is built with a "defense in depth" approach:
1. **Least Privilege:** Runs with a dedicated ServiceAccount.
- **Read-Only:** Most resources (Pods, Events, Flux, Certs).
- **Scoped Action:** `patch` is strictly limited to whitelisted deployments and Flux resources.
- **Scoped Exec:** `pod/exec` is strictly limited to `jellyfin`, `pihole`, and `mcp-homelab` (debug-agent) namespaces via specific Roles.
2. **Input Validation:** Strict validation on all tool inputs (especially for file paths and resource names).
3. **Authentication:** Requires `X-API-Key` header for all requests.
4. **Network:** Designed to run behind an Ingress accessible only via Tailscale.
## 🛠️ Configuration
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `MCP_API_KEY` | Secret key for authenticating requests | Yes |
| `MCP_TRANSPORT` | `stdio` (default) or `sse` | No |
| `NAS_HOST` | Hostname/IP of Synology NAS | Yes (for NAS tools) |
| `NAS_USER` | SSH Username for NAS | Yes (for NAS tools) |
| `NAS_PRIVATE_KEY` | SSH Private Key for NAS | Yes (for NAS tools) |
| `NAS_ALLOWED_PATHS`| Comma-separated list of allowed path prefixes | No (defaults to strict subset) |
| `JELLYFIN_URL` | Internal URL for Jellyfin | No (default: cluster svc) |
| `JELLYFIN_API_KEY` | API Key for Jellyfin operations | Yes (for Media tools) |
| `IMMICH_API_KEY` | API Key for Immich stats | Yes (for Media tools) |
| `BAZARR_URL` | Internal URL for Bazarr | No (default: cluster svc) |
| `BAZARR_API_KEY` | API Key for Bazarr operations | Yes (for Subtitle tools) |
| `SONARR_URL` | Internal URL for Sonarr | No (default: cluster svc) |
| `SONARR_API_KEY` | API Key for Sonarr operations | Yes (for TV tools) |
| `RADARR_URL` | Internal URL for Radarr | No (default: cluster svc) |
| `RADARR_API_KEY` | API Key for Radarr operations | Yes (for Movie tools) |
| `SABNZBD_URL` | Internal URL for SABnzbd | No (default: cluster svc) |
| `SABNZBD_API_KEY` | API Key for SABnzbd operations | Yes (for Download tools) |
## 📦 Deployment
### Local Development (Stdio)
```bash
# Install dependencies
npm install
# Build
npm run build
# Run in stdio mode (for testing with Claude Desktop/CLI)
npm run dev
```
### Kubernetes (Production)
The server is designed to be deployed as a Pod in your cluster.
1. **Build Docker Image:**
```bash
docker build -t ghcr.io/username/homelab-mcp:latest .
```
2. **Deploy Manifests:**
See the `k8s/` directory for example manifests, including:
- `deployment.yaml`
- `service.yaml`
- `ingress.yaml` (configured for Tailscale/Cert-manager)
- `clusterrole.yaml` (Scoped RBAC permissions)
## 🧩 Available Tools
| Category | Tools |
|----------|-------|
| **Cluster** | `get_cluster_health`, `restart_deployment` |
| **DNS** | `get_dns_status`, `test_dns_query`, `update_pihole_gravity`, `get_pihole_whitelist`, `get_pihole_queries` |
| **GitOps** | `get_flux_status`, `reconcile_flux` |
| **Media** | `get_media_status`, `fix_jellyfin_metadata` |
| **Subtitles** | `get_subtitle_status`, `get_subtitle_history`, `search_subtitles` |
| **TV (Sonarr)** | `get_sonarr_queue`, `get_sonarr_history`, `search_sonarr_episode` |
| **Movies (Radarr)** | `get_radarr_queue`, `get_radarr_history`, `search_radarr_movie` |
| **Downloads (SABnzbd)** | `get_sabnzbd_queue`, `get_sabnzbd_history`, `retry_sabnzbd_download`, `pause_resume_sabnzbd` |
| **Arr Shared** | `get_quality_profile`, `reject_and_search` |
| **Backups** | `get_backup_status`, `trigger_backup`, `get_cronjob_details`, `get_job_logs` |
| **Secrets** | `get_secrets_status`, `refresh_secret` |
| **Storage** | `get_pvcs` |
| **Resources** | `describe_resource` |
| **System** | `get_certificate_status`, `get_ingress_status`, `touch_nas_path` |
| **Networking** | `get_node_networking`, `get_iptables_rules`, `get_conntrack_entries`, `curl_ingress`, `test_pod_connectivity` |
| **Logs** | `get_pod_logs` |