Homelab MCP-Server

KI-gestützte Verwaltung der Homelab-Infrastruktur über das Model Context Protocol

Ein Python-MCP-Server, der es KI-Assistenten ermöglicht, Homelab-Infrastruktur zu verwalten, bereitzustellen und zu überwachen. Die Tools umfassen SSH-Erkennung, VM-Verwaltung, Dienstinstallation, Netzwerktopologie-Mapping, Proxmox-Operationen und Anmeldedatenverwaltung.

Hauptfunktionen

• SSH-Erkennung -- Umfassende Hardware- und Softwareinformationen von jedem System erfassen

• Dienstinstallation -- Bereitstellung von Jellyfin, Pi-hole, Ollama, Home Assistant und mehr über Vorlagen

• Proxmox-Integration -- Vollständiger API-Zugriff sowie Erkennung von Community-Skripten

• VM/Container-Lebenszyklus -- Docker- und LXD-Workloads bereitstellen, steuern und entfernen

• Netzwerk-Mapping -- Geräte erkennen, Topologie analysieren und Änderungen verfolgen

• Terraform und Ansible -- Zustandsverwaltete Bereitstellungen mit Drift-Erkennung und Playbooks

• Anmeldedatenverwaltung -- Server einmal registrieren, verbinden ohne erneute Eingabe von Anmeldedaten

Schnelleinstieg

# Install from PyPI (recommended — no clone needed)
uvx homelab-mcp

# Or clone and run from source
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

Für die vollständige Anleitung (Umgebungsvariablen, MCP-Client-Konfiguration, erster Tool-Aufruf), siehe den Einrichtungsleitfaden.

Dokumentation

Funktionsweise

1. Einrichtung -- Der Server generiert beim ersten Start ein SSH-Schlüsselpaar (~/.ssh/mcp_admin_rsa)

2. Host einbinden -- Verwenden Sie setup_mcp_admin, um einen verwalteten Benutzer auf dem Zielsystem zu erstellen

3. Überprüfung -- Verwenden Sie verify_mcp_admin, um den passwortlosen SSH-Zugriff zu bestätigen

4. Verwaltung -- Hardware erkennen, Dienste installieren, VMs steuern und Ihr Netzwerk abbilden

Der Server kommuniziert über stdio unter Verwendung des MCP-Protokolls. Verbinden Sie ihn mit einem beliebigen MCP-kompatiblen Client (Claude Desktop, etc.) und interagieren Sie über natürliche Sprache.

Anmeldedatenverwaltung

Speichern Sie SSH- und Proxmox-Anmeldedaten einmalig, damit der Server sie bei jeder Verbindung automatisch einfügt:

# Store an SSH credential
homelab-mcp credentials add 192.168.1.10 admin

# Store a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox

# List stored credentials
homelab-mcp credentials list
homelab-mcp credentials list --type proxmox

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

Anmeldedaten werden im OS-Keyring gespeichert (libsecret unter Linux, Keychain unter macOS). Wenn der OS-Keyring nicht verfügbar ist (Headless-Server), greifen die Anmeldedaten auf Umgebungsvariablen zurück.

Siehe Credentials CLI-Referenz für die vollständige Dokumentation.

MCP-Client-Konfiguration

Von PyPI (uvx) — empfohlen:

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["homelab-mcp"]
    }
  }
}

Vom Quellcode-Klon:

{
  "mcpServers": {
    "homelab": {
      "command": "uv",
      "args": ["run", "python", "run_server.py"],
      "cwd": "/path/to/homelab_mcp"
    }
  }
}

Entwicklung

# Install with dev dependencies
uv sync --group dev

# Run tests (unit only, no Docker required)
uv run pytest tests/ -m "not integration"

# Code quality
uv run ruff check src/ tests/
uv run mypy src/

Siehe DEPLOYMENT.md für Details zur Produktionsbereitstellung.

Projektstruktur

src/homelab_mcp/
  server.py              # MCP server with JSON-RPC protocol
  tool_schemas/          # Tool definitions (8 schema files)
  tool_annotations.py    # MCP annotation hints per tool
  ssh_tools.py           # SSH discovery and hardware detection
  service_installer.py   # Service installation framework
  infrastructure_crud.py # Infrastructure lifecycle management
  vm_operations.py       # VM/container operations
  sitemap.py             # Network topology mapping
  database.py            # SQLite device tracking
  error_handling.py      # Centralized error handling
  credential_store.py    # OS keyring credential storage
  log_filter.py          # Credential redaction for log output
  prompt_registry.py     # MCP prompts registry
  resource_readers.py    # MCP resource read handlers
  service_templates/     # YAML service definitions
tests/                   # Unit and integration tests
docs/                    # Full documentation

Danksagungen

Die Integration der Proxmox-Community-Skripte wird durch community-scripts/ProxmoxVE (MIT-Lizenz) ermöglicht.

Mitwirken

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch

3. Schreiben Sie Tests für neue Funktionen

4. Stellen Sie sicher, dass alle Tests bestehen

5. Senden Sie einen Pull Request

Lizenz

MIT-Lizenz -- siehe LICENSE-Datei für Details.