MCP Hub

Ein MCP-Server, der Ihrem KI-Assistenten die Schlüssel zu Ihrem gesamten Homelab gibt.

MCP Hub ist ein einzelner Model Context Protocol-Server, der auf einem Rechner in Ihrem Netzwerk sitzt und von dort aus verteilt: SSH zu jedem Host in Ihrer Flotte, Proxmox-Container, Docker, Synology DSM, Cloudflare-Tunnel und DNS, n8n-Workflows, Notion, Ihr Passwort-Tresor. Anstatt ein Dutzend MCP-Server zu betreiben und jeden in Ihren Client einzubinden, führen Sie einen aus und richten Ihren Assistenten darauf aus.

"Warum ist Jellyfin nicht erreichbar?" — und der Assistent überprüft den Container, liest das Journal, stellt fest, dass der Tunnel-Ingress veraltet ist, repariert ihn und teilt Ihnen mit, was er getan hat.

⚠️ Lesen Sie SECURITY.md, bevor Sie dies bereitstellen. MCP Hub gibt einem LLM Root-Shell-Zugriff auf Ihre gesamte Flotte. Das ist der Sinn der Sache, und es ist wirklich gefährlich. Die Standardeinstellungen sind sicher (127.0.0.1, schreibgeschützt); die Gefahr beginnt, wenn Sie sie ändern.

Troubleshooting-Demo

Das Repository enthält eine bereinigte Asciicast-Aufzeichnung einer vollständigen, beobachtungsbasierten Fehlerbehebungssitzung: fehlgeschlagener Endpunkt, systemd-Diagnose, exakter Mutationsplan, explizite Bestätigung, Neustart und abschließende Health-Checks. Sie verwendet das Beispiel-Inventar und enthält keine privaten Infrastrukturdaten.

asciinema play docs/troubleshooting.cast

Siehe die Aufzeichnung direkt, wenn Asciinema nicht installiert ist; das Cast-Format ist zeilengetrenntes JSON und bleibt überprüfbar.

Related MCP server: homelab-mcp

Inhalt

• Funktionen

• Schnellstart

• Bereitstellung

• Lokale Tests

• Rescue-Diagnose

• Konfiguration

• Tool-Referenz

• Sicherheit

• Versionierung

• Mitwirken

Funktionen

• 111 Tools, ein Endpunkt, eine Konfigurationsdatei.

• Konfigurationsgesteuert. Ihr Netzwerk lebt in hosts.yaml und .env. Nichts an Ihrer Infrastruktur ist im Code fest verdrahtet.

• Multiplexed SSH. Permanente Control-Sockets, sodass flottenweite Befehle Millisekunden statt eines TCP-Handshakes pro Stück benötigen.

• Optionale Integrationen. Jede Integration ist standardmäßig deaktiviert und mit einem einzigen Flag aktivierbar. Führen Sie es als reines SSH-Flotten-Tool aus, wenn das alles ist, was Sie möchten.

• Ansteckbare Geheimnisse. Lesen Sie Anmeldedaten aus der Umgebung oder aus einem Bitwarden/Vaultwarden-Tresor über bw serve.

• Bearer-Token-Authentifizierung auf Basis eines unerratbaren Endpunkt-Pfads.

• Globaler schreibgeschützter Modus, standardmäßig aktiviert: Ein Flag deaktiviert alle 43 mutierenden Tools, zentral durchgesetzt und nicht Tool für Tool.

• Automatische Schwärzung von Geheimnissen in Dateiauslesungen und Befehlsausgaben.

• Hintergrundjobs mit Polling, Logs und einem persistenten SQLite-Zustandsspeicher.

Schnellstart

Erfordert Python 3.11+ und einen Linux-Host mit SSH-Zugriff auf die Maschinen, die Sie verwalten möchten.

git clone https://github.com/wnx82/mcp-hub.git
cd mcp-hub

python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env                  # then edit — see below
cp hosts.example.yaml hosts.yaml      # then edit: your fleet
chmod 600 .env hosts.yaml

python server.py

Setzen Sie mindestens diese beiden in .env:

MCP_SECRET_PATH=/$(openssl rand -hex 16)   # unguessable endpoint path
MCP_AUTH_TOKEN=$(openssl rand -hex 32)     # bearer token — the real auth

Der Server lauscht dann auf http://127.0.0.1:8000<MCP_SECRET_PATH>, mit MCP_READ_ONLY=true. Richten Sie Ihren MCP-Client auf diese URL und senden Sie Authorization: Bearer <MCP_AUTH_TOKEN>. Anfragen ohne Token erhalten eine 401; Anfragen an einen anderen Pfad erhalten eine 404.

Für einen lokalen MCP-Client, der stdio statt HTTP wünscht, starten Sie denselben Hub mit:

mcp-hub --transport stdio

oder setzen Sie MCP_TRANSPORT=stdio in der Umgebung vor dem Start.

Für eine systemd-Bereitstellung erstellt sudo ./deploy/install.sh einen dedizierten mcphub-Benutzer und SSH-Schlüssel, generiert beide Geheimnisse in /etc/default/mcp-hub und installiert die Unit. Es ist idempotent und überschreibt niemals vorhandene Konfiguration. Siehe deploy/.

Für ein vollständiges Claude Code-Setup, sichere Token-Handhabung, Verbindungsprüfungen, eine erste schreibgeschützte Aufforderung und die aktuelle Claude Desktop-Einschränkung siehe Connect MCP Hub to Claude.

Wenn Sie möchten, dass Ihr Assistent Ihre private Topologie, Host-Rollen, Änderungsfenster und MCP-Betriebsregeln versteht, ohne diese Daten festzuschreiben, beginnen Sie mit PROJECT_INSTRUCTIONS.example.md und behalten Sie Ihre angepasste PROJECT_INSTRUCTIONS.md lokal.

Bereitstellung

MCP Hub unterstützt drei Ausführungsmodi:

Das Python-Paket und die direkte Ausführung verwenden den aktuellen Checkout und seine virtuelle Umgebung. Sie erstellen keinen Dienst-Account, SSH-Schlüssel, keine Umgebungsdatei oder Neustart-Richtlinie. Der systemd-Installer stellt diese betrieblichen Teile bereit, belässt die lokale Konfiguration bei erneuter Ausführung intakt und installiert Rescue außerhalb der Hub-Virtualenv.

Container-Images sind noch kein offizielles Bereitstellungsziel. Der Hub benötigt Netzwerkzugriff, eine SSH-Identität, persistente state.db und Zugriff auf sein lokales Inventar; Betreiber, die ihn in einen Container verpacken, müssen diese Eigenschaften selbst bewahren.

Siehe docs/docker-packaging.md für die aktuellen Anforderungen und was ein offizielles Image garantieren müsste, bevor es empfohlen werden kann.

Lokale Tests

Für eine mitwirkendenorientierte Checkliste, die Lint, Unit-Tests, Tool-Registrierung, generierte Dokumente, Installer-Smoke-Tests und einen manuellen schreibgeschützten Durchlauf abdeckt, siehe docs/testing-local.md.

Für die MCP-2026-07-28-Migrationszusammenfassung, Kompatibilitätsmatrix und Rollback-Verfahren siehe docs/migration/mcp-2026-07-28-guide.md.

Bevor Sie einen PR öffnen oder einen Branch veröffentlichen, können Sie auch die lokalen Release-Bereitschaftsprüfungen ausführen:

python3 scripts/check_repo_hygiene.py
python3 scripts/check_tool_annotations.py
python3 scripts/check_security_readiness.py

Um die Sicherheitsbereitschaftsprüfung automatisch per Push in Git einzubinden:

./scripts/install_pre_push_hook.sh

Architektur

server.py bleibt die MCP-Server-Kompositionswurzel, während der Domänencode schrittweise in tools/ verschoben wird. SSH-Befehlsaufbau, Cloudflare-Pfade und Antwortextraktion, DSM-Protokollmetadaten, Inventar und Playbook-Ersteller sind bereits isoliert. tools/registry.py weist extrahierte Tools einer Domäne zu; diese Domäne ist in jeder Prüfzusammenfassung enthalten. Neue Protokolllogik sollte in ihrem Domänenmodul leben und darf server.py nicht importieren.

Zukünftige Integrationen werden in docs/integration-evaluation.md priorisiert, einschließlich ihres Least-Privilege-Bereichs und ihrer Promotionsstufen.

Rescue-Diagnose

mcp-hub-rescue ist ein schreibgeschütztes lokales CLI, das so konzipiert ist, dass es funktioniert, wenn der Hauptserver nicht importieren kann oder seine Virtualenv defekt ist. Der systemd-Installer kopiert es nach /opt/mcp-hub-rescue und führt es mit dem System-Python außerhalb des MCP Hub-Prozesses und der Virtualenv aus.

sudo mcp-hub-rescue doctor
sudo mcp-hub-rescue status
sudo mcp-hub-rescue health
sudo mcp-hub-rescue logs --lines 50
sudo mcp-hub-rescue validate-config

Ergebnisse sind strukturiertes JSON. Rescue importiert niemals server.py, tools/*, MCP oder eine optionale Integration, und diese Grenze wird von CI durchgesetzt. Die aktuellen Befehle beobachten und diagnostizieren nur; Neustart-, Reparatur- und Rollback-Operationen werden separat mit Bestätigung und Last-Known-Good-Sicherungen hinzugefügt.

Konfiguration

Alle git-ignoriert — jede hat eine getrackte .example-Vorlage:

Ein Host-Eintrag ist minimal gehalten:

hosts:
  nas:
    hostname: nas.example.lan
    user: admin
    role: storage
    tags: [nas, backup]
    mac: "aa:bb:cc:dd:ee:01"   # optional, enables wake_host()

Tags sind, wie Sie Gruppen adressieren: fleet_exec(tag="backup", command="df -h"). Für ein kopierfertiges Zwei-Host-Inventar beginnen Sie mit docs/examples/hosts.minimal.yaml. Das größere hosts.example.yaml demonstriert jede unterstützte Host-Option.

Kombinieren Sie es mit docs/examples/topology.guarded.yaml, um Proxmox-Gäste zu kartieren, veraltete Adressfallen zu protokollieren und Infrastruktur zu kennzeichnen, die nicht leichtfertig geändert werden darf. Die _do_not_touch-Einträge sind betrieblicher Kontext für den Assistenten, keine durchgesetzte Zugriffsgrenze; verwenden Sie Token-Profile und Host-Einschränkungen für die technische Durchsetzung.

Fügen Sie docs/examples/endpoints.minimal.yaml hinzu, um immer aktive und intermittierende HTTP-Dienste zu überwachen. Rufen Sie endpoints_health() für die reguläre Menge oder endpoints_health(include_intermittent=true) auf, um Dienste einzubeziehen, die normalerweise ausgeschaltet sein können. Antworten von 200 bis 399 gelten als gesund; Weiterleitungen werden nicht verfolgt.

Die vollständigen Standardwerte, Grenzen, Integrationseinstellungen und Hinweise zur Geheimnisbehandlung finden Sie in der Umgebungsvariablen-Referenz.

Kombinieren Sie diese getrackten Beispiele mit einer privaten, ungetrackten PROJECT_INSTRUCTIONS.md, damit Ihr Assistent Topologie-Hinweise, Wartungsfenster, Namenskonventionen und „Nicht anfassen“-Anleitungen sieht, die nicht im Repository leben sollten.

Tool-Referenz

Jedes Tool gibt denselben Umschlag auf oberster Ebene zurück:

{
  "ok": true,
  "data": {},
  "error": null,
  "duration_ms": 12,
  "host": "example",
  "request_id": "4d52b1f69b974b7784bf65dd",
  "tool": "system_info"
}

data enthält die toolspezifische Nutzlast. Sicherheitsverweigerungen und kontrollierte Ausnahmen verwenden dieselbe Form mit ok: false, wodurch verkettete Aufrufe und Prüfkorrelation vorhersagbar werden.

Der zentrale Tool-Wrapper begrenzt auch die Anfragegröße, Aufrufe pro Token, gleichzeitige Aufrufe pro Ziel, wiederholte Zielfehler und Mutationshäufigkeit. Standardwerte sind in .env.example dokumentiert; Grenzverweigerungen verwenden denselben Antwortumschlag und Prüfpfad wie jeder andere Aufruf.

Die vollständige generierte Tool-Referenz erweitert jede Gruppe zu einer Tabelle mit der genauen Signatur und der modellseitigen Beschreibung jedes Tools. CI überprüft sie gegen die registrierten Funktionen.

Die geführte Diagnose stoppt immer nach der Beobachtung. Sie liefert Nachweise, Bewertung und empfohlene nächste Schritte mit correction_applied: false; check_backup_chain ist ein Frische- und Speichersignal, kein Beweis dafür, dass eine Wiederherstellung gelingt.

Sicherheit

MCP Hub ist ein Dienst zur Remote-Code-Ausführung von Grund auf. Bevor Sie ihn freigeben:

• Behalten Sie die Standardbindung 127.0.0.1 bei oder setzen Sie sie hinter einen Tunnel mit Zugriffsrichtlinien.

• Setzen Sie MCP_AUTH_TOKEN – der geheime URL-Pfad ist Verschleierung, keine Authentifizierung.

• Lassen Sie MCP_READ_ONLY=true, bis Sie vertrauen, was Ihr Modell damit macht.

• Behalten Sie die Standardeinstellungen des Ressourcenschutzes aktiviert und passen Sie sie dann anhand des beobachteten Audit-Traffics an, anstatt sie zu deaktivieren.

• Geben Sie ihm einen dedizierten SSH-Schlüssel und eine minimale hosts.yaml.

Vollständiges Bedrohungsmodell, Härtungsleitfaden und Schwachstellenmeldung: SECURITY.md.

Für eine lokale Pre-Publish-Checkliste und einen optionalen Git-Hook, der häufige Fehler bei Geheimnislecks vor dem Push abfängt, siehe scripts/check_security_readiness.py und scripts/install_pre_push_hook.sh.

Versionierung

SemVer. Vor 1.0 werden Breaking Changes in der Nebenversion hochgezogen – lesen Sie daher die Hinweise unter Changed und Removed, bevor Sie ein Upgrade durchführen. _version.py ist die einzige Quelle der Wahrheit; der laufende Server meldet sie über mcp-hub --version, im MCP-Handshake und in mcp_health.

Jede Version ist in CHANGELOG.md dokumentiert, wobei sicherheitsrelevante Änderungen in einem eigenen Abschnitt hervorgehoben werden.

Mitwirken

Issues und Pull-Requests sind willkommen – insbesondere Fehlerberichte, neue Integrationen und Dokumentationskorrekturen. Siehe CONTRIBUTING.md.

Lizenz

MIT © wnx82