Homelab MCP-Server

👁 CI
👁 Python 3.12+
👁 License: MIT

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

🏆 TestSprite Season 2 Hackathon-Einreichung

Branch: TestSprite_Hackathon | Endgültige Erfolgsquote: 10/10 (100%)

Was ich gebaut habe

homelab_mcp ist ein MCP-Server (Model Context Protocol) – er spricht kein REST. TestSprite testet REST-APIs. Die Kernherausforderung dieser Einreichung bestand darin, diese Protokoll-Lücke zu schließen.

Die Lösung: Ein FastAPI-Wrapper, der alle 56 MCP-Tools als korrekte REST-Endpunkte bereitstellt, komplett mit einem dokumentierten HTTP-Fehlervertrag, sodass TestSprite die gesamte Tool-Oberfläche ohne MCP-Protokollkenntnisse testen kann.

TestSprite Agent → FastAPI wrapper (port 8080) → homelab_mcp tools → Infrastructure

Design des Fehlervertrags

Anstatt generische 500er-Fehler zurückzugeben, implementiert der Wrapper einen dreistufigen HTTP-Fehlervertrag:

Das Design 424 Failed Dependency ist der interessanteste Teil. Tools, die mit echter Infrastruktur kommunizieren (SSH-Hosts, Proxmox API, TrueNAS), führen einen TCP-Preflight-Test durch, bevor der Handler aufgerufen wird. Wenn das Ziel nicht erreichbar ist, gibt der Wrapper einen 424-Fehler mit einer strukturierten Nutzlast zurück – status, host, port, protocol und ein requires-Hinweis zur Fehlerbehebung –, ohne den Handler jemals zu berühren. Keine Teilausführung, kein Durchsickern von Anmeldeinformationen an nicht erreichbare Hosts.

Sobald dieser Vertrag in der Swagger-Spezifikation dokumentiert war, generierte TestSprite automatisch Negativ-Testfälle für alle drei Fehlertypen.

Testergebnisse — Fünf-Durchlauf-Zyklus

Durch TestSprite gelieferte Korrekturen

Ausführen der TestSprite-Testsuite

# Clone the hackathon branch
git clone -b TestSprite_Hackathon https://github.com/washyu/homelab_mcp.git
cd homelab_mcp

# Install dependencies
uv sync

# Start the FastAPI wrapper (no auth mode for testing)
uv run python run_server.py --openapi --port 8080 --no-auth

# TestSprite test cases are in testsprite_tests/
# Run via the TestSprite agent pointed at http://localhost:8080

Gelernte Lektionen

1. MCP-Server benötigen eine REST-Fassade für konventionelle API-Test-Tools

2. Ihre Swagger-Spezifikation ist Ihr Testplan – dokumentieren Sie Fehlerverträge und TestSprite generiert Tests dafür

3. Genauigkeit von code_summary.yaml ist wichtig – falsche Feldnamen erzeugen falsche Tests

4. Fügen Sie CLAUDE.md-Leitplanken hinzu, bevor Sie Claude Code in die Nähe von TestSprite lassen – ohne diese wird es autonom in einer Schleife aus Korrektur→Neustart feststecken und Credits verbrauchen

5. Schließen Sie testsprite_tests/ von Ihrem Linter und Formatter aus – behandeln Sie es wie vendor/

6. Berichte nach jedem Durchlauf committen oder kopieren – die Zusammenfassung wird jedes Mal überschrieben

7. Auth- und No-Auth-Modi erfordern separate Durchläufe – können nicht beide in einer TestSprite-Sitzung abgedeckt werden

Vollständiger Bericht: shaunjackson.space

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, Netzwerk-Topologie-Mapping, Proxmox-Operationen und Anmeldeinformationsverwaltung.

Hauptfunktionen

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

• Dienstinstallation -- Jellyfin, Pi-hole, Ollama, Home Assistant und mehr aus Vorlagen bereitstellen

• Proxmox-Integration -- Voller API-Zugriff sowie Erkennung von Community-Skripten

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

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

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

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

Schnellstart

# 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 Setup-Guide.

Dokumentation

Funktionsweise

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

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

3. Verifizieren -- Verwenden Sie verify_mcp_admin, um den passwortlosen SSH-Zugriff zu bestätigen

4. Verwalten -- Hardware entdecken, 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.

Anmeldeinformationsverwaltung

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

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

# Store an SSH key-based credential (stores the key file path in the keyring, not the key)
homelab-mcp credentials add 192.168.1.10 admin --key-path ~/.ssh/id_ed25519

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

# Update an existing credential — `add` is upsert; re-running replaces the stored entry
homelab-mcp credentials add 192.168.1.10 admin

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

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

Die CLI bietet vollständiges CRUD für Anmeldedaten: add (erstellen/aktualisieren – upsert), list (lesen), remove (löschen). Es gibt keinen separaten update-Unterbefehl – ein erneutes Ausführen von add ersetzt sowohl das Keyring-Geheimnis als auch den Authentifizierungstyp des Registrierungseintrags.

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
testsprite_tests/ # TestSprite generated test suite (hackathon)
tests/ # Unit and integration tests
docs/ # Full documentation

Danksagungen

Proxmox-Community-Skript-Integration unterstützt durch community-scripts/ProxmoxVE (MIT-Lizenz).

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.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• analyze_network_topologyB
• bulk_discover_and_mapA
• check_ansible_serviceB
• check_service_requirementsA
• clone_proxmox_vmB
• control_vmB
• create_infrastructure_backupC
• create_proxmox_lxcB