convez.ai
MCP ServerDevOps & InfraestruturaAvançado
mtgibbs

Pi Cluster MCP – Gerenciamento Seguro de Homelab

mtgibbs/pi-cluster-mcp

Controle seu homelab K3s via Claude com segurança e estrutura

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta Claude ao seu homelab Kubernetes (K3s em Raspberry Pi) de forma segura. Oferece ferramentas estruturadas para operações K3s, gerenciamento DNS Pi-hole, controle de Jellyfin/Immich e diagnósticos de rede, com arquitetura focada em segurança e princípio do menor privilégio.

Instalação

$npx convez-ai mtgibbs/pi-cluster-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 semanas
Versão
v0.2.1
Issues abertas
4
Contribuidores
2

Casos de uso

  • Monitorar saúde e recursos de cluster Kubernetes a partir de Claude
  • Gerenciar DNS, backup e GitOps (Flux) sem SSH direto
  • Inspecionar e controlar serviços de mídia (Jellyfin, Immich) remotamente
  • Executar diagnósticos de rede, conectividade e firewall no cluster
  • Automatizar restarts e triggers de jobs com validação de entrada

Veredito

Solução robusta e bem-pensada para quem quer expor operações homelab a Claude sem comprometer segurança. Arquitetura de least privilege e validação rigorosa elevam o padrão; ideal para usuários avançados com K3s e DNS caseiros.

README

A tradução para o português deste README ainda está na fila.

Homelab MCP Server

A Model Context Protocol (MCP) 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

VariableDescriptionRequired
MCP_API_KEYSecret key for authenticating requestsYes
MCP_TRANSPORTstdio (default) or sseNo
NAS_HOSTHostname/IP of Synology NASYes (for NAS tools)
NAS_USERSSH Username for NASYes (for NAS tools)
NAS_PRIVATE_KEYSSH Private Key for NASYes (for NAS tools)
NAS_ALLOWED_PATHSComma-separated list of allowed path prefixesNo (defaults to strict subset)
JELLYFIN_URLInternal URL for JellyfinNo (default: cluster svc)
JELLYFIN_API_KEYAPI Key for Jellyfin operationsYes (for Media tools)
IMMICH_API_KEYAPI Key for Immich statsYes (for Media tools)
BAZARR_URLInternal URL for BazarrNo (default: cluster svc)
BAZARR_API_KEYAPI Key for Bazarr operationsYes (for Subtitle tools)
SONARR_URLInternal URL for SonarrNo (default: cluster svc)
SONARR_API_KEYAPI Key for Sonarr operationsYes (for TV tools)
RADARR_URLInternal URL for RadarrNo (default: cluster svc)
RADARR_API_KEYAPI Key for Radarr operationsYes (for Movie tools)
SABNZBD_URLInternal URL for SABnzbdNo (default: cluster svc)
SABNZBD_API_KEYAPI Key for SABnzbd operationsYes (for Download tools)

📦 Deployment

Local Development (Stdio)

# 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:

    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

CategoryTools
Clusterget_cluster_health, restart_deployment
DNSget_dns_status, test_dns_query, update_pihole_gravity, get_pihole_whitelist, get_pihole_queries
GitOpsget_flux_status, reconcile_flux
Mediaget_media_status, fix_jellyfin_metadata
Subtitlesget_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 Sharedget_quality_profile, reject_and_search
Backupsget_backup_status, trigger_backup, get_cronjob_details, get_job_logs
Secretsget_secrets_status, refresh_secret
Storageget_pvcs
Resourcesdescribe_resource
Systemget_certificate_status, get_ingress_status, touch_nas_path
Networkingget_node_networking, get_iptables_rules, get_conntrack_entries, curl_ingress, test_pod_connectivity
Logsget_pod_logs
Ver o original no GitHub

Bom para

Relacionados