Zum Inhalt

Homelab MCP – Proxmox-Anbindung

Stand 08.09.2026: Das neue homelab-mcp auf CT 109 ist über eine interne SSH-Capability mit dem Proxmox-Host verbunden. Der Zugriff läuft über den bestehenden eingeschränkten Benutzer mcp-agent und den root-eigenen Wrapper /usr/local/bin/mcp-pct. Ein allgemeines SSH- oder Shell-Tool wird nicht über MCP bereitgestellt.

Ziel

Die Proxmox-Anbindung soll semantische MCP-Tools anbieten, ohne dem MCP-Client freie SSH-Befehle oder uneingeschränktes sudo zu geben.

flowchart LR
    MCP["homelab-mcp"] --> POLICY["Plugin-/Tool-Policy"]
    POLICY --> PVEPLUGIN["Proxmox Plugin"]
    PVEPLUGIN --> SSH["interne SSH-Capability"]
    SSH --> AGENT["mcp-agent@Proxmox"]
    AGENT --> WRAPPER["sudo /usr/local/bin/mcp-pct"]
    WRAPPER --> PCT["pct"]

SSH-Prinzip

SSH ist ausschließlich eine interne Capability. Die Capability kennt nur explizit konfigurierte:

  • Zielsysteme;
  • SSH-Benutzer;
  • Identity-Dateien;
  • known_hosts-Dateien;
  • Plugins, die das Ziel verwenden dürfen;
  • Command-IDs;
  • feste Kommando-Tokens;
  • streng validierte dynamische Parameter.

Es existiert bewusst kein MCP-Tool wie:

ssh_execute
shell_execute

Dedizierter Schlüssel für CT 109

CT 109 besitzt einen eigenen ED25519-Schlüssel nur für den Zugriff auf Proxmox.

Lokal auf CT 109:

/etc/homelab-mcp/ssh/proxmox_ed25519
/etc/homelab-mcp/ssh/proxmox_ed25519.pub

Rechte des privaten Schlüssels:

root:homelab-mcp 0640

Der Schlüssel wird nicht aus CT 108 wiederverwendet und nicht im GitHub-Repository gespeichert.

Proxmox-Hostkey

Vor dem ersten Zugriff von CT 109 wurde der ED25519-Hostkey des Proxmox-Hosts per ssh-keyscan aus CT 109 ermittelt und exakt mit dem bereits auf CT 108 vertrauenswürdigen Proxmox-Hostkey verglichen.

Nur nach erfolgreicher Übereinstimmung wurde der Hostkey nach CT 109 übernommen:

/etc/homelab-mcp/ssh/known_hosts

Die SSH-Capability verwendet immer:

StrictHostKeyChecking=yes

Eine pauschale Abschaltung der Hostkey-Prüfung ist nicht vorgesehen.

Einschränkung des Proxmox-Schlüssels

Der Public Key von CT 109 wurde beim bestehenden Proxmox-Benutzer mcp-agent hinterlegt und zusätzlich auf die Quell-IP von CT 109 beschränkt:

restrict,from="10.10.10.50" ...

Damit kann dieser Schlüssel nicht von beliebigen anderen Hosts verwendet werden.

Bestehender Proxmox-Wrapper

Der root-eigene Wrapper auf Proxmox ist:

/usr/local/bin/mcp-pct

Er erlaubt aktuell ausschließlich:

list
status <CT-ID>
start <CT-ID>
stop <CT-ID>
restart <CT-ID>
exec <CT-ID> systemctl <status|start|stop|restart> <service>
exec <CT-ID> journalctl-unit <service> <n>
exec <CT-ID> journalctl-clear

Container-IDs müssen numerisch sein. Freie pct exec-Befehle sind nicht möglich.

Das neue Proxmox-Plugin verwendet aktuell nur die direkt benötigten Wrapper-Kommandos für Containerliste und Containerstatus. Die Zustandsänderungen sind zwar im Plugin vorbereitet, aber durch die Tool-Policy gesperrt.

Lokale SSH-Konfiguration auf CT 109

Die installationsspezifische SSH-Capability-Konfiguration liegt außerhalb des Repositorys:

/etc/homelab-mcp/ssh.json

Darin ist für das Ziel proxmox festgelegt:

Host: 10.10.10.10
User: mcp-agent
Identity: /etc/homelab-mcp/ssh/proxmox_ed25519
Known hosts: /etc/homelab-mcp/ssh/known_hosts
Plugin-Allowlist: proxmox

Die Command-IDs sind ebenfalls fest konfiguriert. Dynamisch ist beim Containerstatus beziehungsweise bei Zustandsänderungen nur die numerische containerId.

Die generische Vorlage ohne private Infrastrukturwerte liegt im Repository unter:

config/ssh.example.json

Härtung des SSH-Clients

Die interne SSH-Capability startet den Client unter anderem mit:

BatchMode=yes
IdentitiesOnly=yes
StrictHostKeyChecking=yes
PasswordAuthentication=no
KbdInteractiveAuthentication=no
ForwardAgent=no
ClearAllForwardings=yes
ConnectTimeout=5

Zusätzlich gelten:

  • Timeout für Remote-Kommandos;
  • Ausgabegrößenlimit;
  • kein geerbter breiter System-PATH;
  • Plugin-zu-Ziel-Allowlist;
  • Command-ID-Allowlist;
  • Parameterprüfung vor Prozessstart.

MCP-Tools

Das Plugin deklariert aktuell:

Tool Risiko Stand auf CT 109
proxmox_list_containers read freigegeben
proxmox_get_container_status read freigegeben
proxmox_start_container write gesperrt
proxmox_stop_container write gesperrt
proxmox_restart_container write gesperrt

Die aktive Policy auf CT 109 lautet für Proxmox:

read=true
write=false
destructive=false

Deshalb erscheinen die drei write-Tools nicht in tools/list und können über MCP nicht aufgerufen werden.

Erfolgreicher Live-Test

Der laufende MCP-Dienst auf CT 109 wurde über einen temporären SSH-Forward von CT 108 mit dem offiziellen MCP-v2-Client getestet.

Sichtbare Tools waren genau:

system_status
proxmox_list_containers
proxmox_get_container_status

Geprüft wurden unter anderem:

  1. Containerliste über proxmox_list_containers;
  2. CT 109 ist in der Liste vorhanden und läuft;
  3. proxmox_get_container_status für CT 109 liefert running;
  4. proxmox_start_container, proxmox_stop_container und proxmox_restart_container sind nicht sichtbar;
  5. Proxmox-Aufrufe werden im privileggetrennten MCP-Audit als read protokolliert.

Es wurde bei diesen Tests kein Container gestartet, gestoppt oder neu gestartet.

Sicherheitsgrenze

Selbst wenn ein Plugin-Codefehler versuchen würde, einen unbekannten SSH-Befehl zu verwenden, greifen mehrere Grenzen:

  1. Plugin-Manifest und MCP-Policy;
  2. interne Capability-Ziel-Allowlist;
  3. Plugin-Allowlist am SSH-Ziel;
  4. Command-ID-Allowlist;
  5. Parameterprüfung;
  6. eingeschränkter mcp-agent;
  7. root-eigener mcp-pct-Wrapper;
  8. Proxmox-sudo-Regeln.

Nächste Schritte

Die drei write-Tools bleiben zunächst gesperrt. Eine spätere Freigabe soll ausschließlich über die Admin-Oberfläche und die Default-Deny-Policy erfolgen.

Vorher wird die Admin-Oberfläche auf CT 109 als eigener lokaler Dienst fertiggestellt und getestet.