Hermes n8n MCP Plus

Lokale stdio-MCP-Brücke zur Verwaltung von n8n von Hermes Agent aus — jetzt mit Schreib-Tools.

Dies ist ein Fork von CyberSamuraiX/hermes-n8n-mcp, erweitert um create_workflow, update_workflow und delete_workflow auf Basis des ursprünglichen schreibgeschützten/Operations-Toolsets. Es bietet Hermes die vollständige n8n-Workflow-Verwaltung, ohne n8n über das öffentliche Internet zugänglich zu machen und ohne API-Schlüssel in deiner Hermes-Konfiguration abzulegen.

Was es tut

Stellt diese MCP-Tools bereit:

• health — prüft die Erreichbarkeit der n8n-API und optional den Docker-Containerstatus

• list_workflows — listet Workflows auf, optional nach aktivem Status gefiltert

• get_workflow — inspiziert einen Workflow, wobei Felder mit Geheimnissen geschwärzt sind

• find_workflows — durchsucht Workflow-Metadaten

• list_executions — listet letzte Ausführungen auf

• get_execution — inspiziert eine Ausführung; die Payload-Daten sind standardmäßig deaktiviert

• recent_failures — letzte fehlgeschlagene/fehlerhafte Ausführungen

• export_workflow — ruft geschwärztes Workflow-JSON für Backup/Überprüfung ab

• activate_workflow — aktiviert einen Workflow per ID

• deactivate_workflow — deaktiviert einen Workflow per ID

• container_logs — optionale Docker-Logs mit zeilenweiser Schwärzung

• create_workflow — erstellt einen neuen Workflow aus einer JSON-Definition. Standardmäßig als Dry-run.

• update_workflow — patcht einen bestehenden Workflow per ID (Name, Knoten, Verbindungen, Einstellungen, Tags). Zeigt den aktuellen Zustand vor dem Anwenden an. Standardmäßig als Dry-run.

• delete_workflow — löscht einen Workflow dauerhaft per ID. Zeigt vor dem Löschen eine Export-Backup-Vorschau an. Standardmäßig als Dry-run.

Alle drei Schreib-Tools erfordern ein explizites confirm=true-Argument, um tatsächlich etwas zu verändern. Bei Aufruf mit confirm=false (Standard) geben sie eine Vorschau dessen zurück, was passieren würde, und tätigen keinen API-Aufruf, der n8n verändert.

Related MCP server: n8n-ops-mcp

Sicherheitsvorkehrungen

• Nur Stdio. Kein HTTP-Server. Kein öffentlicher Port.

• Der API-Schlüssel wird aus der Umgebung oder aus einer lokalen dotenv-Datei geladen.

• .env ist gitignoriert.

• Die Beispielkonfiguration verwendet REPLACE_ME, niemals einen echten Schlüssel.

• Tool-Antworten schwärzen offensichtliche Credential-, Token-, Secret-, Passwort- und Autorisierungsfelder.

• Die Payload-Daten der Ausführung sind in get_execution standardmäßig deaktiviert.

• Workflow-Aktivierung/-Deaktivierung, Erstellen, Aktualisieren und Löschen sind allesamt Produktionsänderungen. Behandle sie wie geladene Waffen.

• Schreib-Tools führen standardmäßig nur eine Dry-run-Vorschau aus; nichts wird erstellt, gepatcht oder gelöscht, außer der Aufrufer übergibt explizit confirm=true.

• delete_workflow ruft vor einem bestätigten Löschen immer eine Export-/Backup-Vorschau des Workflows ab.

Voraussetzungen

• Python 3.10+

• Hermes Agent mit aktiviertem nativem MCP

• n8n-API-Schlüssel

• n8n erreichbar von der Maschine, auf der Hermes läuft, normalerweise http://127.0.0.1:5678

Kritische Abhängigkeits-Fixierung: mcp==1.29.0

Das offizielle PyPI-Paket mcp hat am 2026-07-28 ein abwärtsinkompatibles Release v2.0.0 veröffentlicht, das mcp.server.fastmcp vollständig entfernt hat (umbenannt in MCPServer, Modulpfade verschoben, httpx durch httpx2 ersetzt und mehr). Wenn requirements.txt eine lockere Einschränkung wie mcp>=1.29.0 verwendet, wird pip install auf 2.0.0 aufgelöst und der Server stürzt beim Import ab mit:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

Dieses Repository fixiert mcp==1.29.0 (die letzte stabile Version vor v2) als feste Version, nicht als Untergrenze. Lockere diese Einschränkung nicht, bis die Codebasis auf die v2-MCPServer-API migriert ist. Falls du den obigen Fehler jemals siehst, überprüfe pip show mcp — wenn es 2.0.0 oder neuer meldet, führe aus:

pip uninstall -y mcp
pip install "mcp==1.29.0"

Installation

git clone https://github.com/csenguttuvan/hermes-n8n-mcp-plus.git
cd hermes-n8n-mcp-plus
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Verifiziere, dass die Installation auf der richtigen SDK-Version gelandet ist, bevor du weitermachst:

pip show mcp
python -c "from mcp.server.fastmcp import FastMCP; print('OK')"

Speichere deinen n8n-Schlüssel

Manuelle Version:

install -d -m 700 ~/.config/n8n-mcp-plus
cat > ~/.config/n8n-mcp-plus/env <<'EOF'
N8N_BASE_URL=http://127.0.0.1:5678
N8N_API_KEY=REPLACE_ME
N8N_MCP_TIMEOUT=30
N8N_CONTAINER_NAME=n8n
N8N_MCP_ALLOW_DOCKER_LOGS=true
EOF
chmod 600 ~/.config/n8n-mcp-plus/env

Ersetze REPLACE_ME lokal. Committe die echte Datei nicht.

Die Tools dieses Forks lesen N8N_API_KEY / N8N_API_URL auch direkt aus der Umgebung, nicht nur aus einer dotenv-Datei, sodass du sie alternativ direkt aus ~/.hermes/config.yaml per ${N8N_API_KEY}-Interpolation injizieren kannst — siehe unten.

Hermes-Konfiguration

Füge dies unter mcp_servers zu ~/.hermes/config.yaml hinzu. Wenn die ursprüngliche n8n-Brücke bereits registriert ist, füge dies als zweiten, separaten Eintrag (n8n_plus) hinzu, anstatt es zu ersetzen — so bleibt ein sicherer schreibgeschützter Fallback verfügbar:

mcp_servers:
  n8n:
    command: /Users/admin/.hermes/mcp-installs/n8n/.venv/bin/python
    args:
      - /Users/admin/.hermes/mcp-installs/n8n/server.py
    enabled: true
    env:
      N8N_API_KEY: "${N8N_API_KEY}"
      N8N_API_URL: "http://localhost:5678/api/v1"

  n8n_plus:
    command: /Users/admin/projects/hermes-n8n-mcp-plus/.venv/bin/python
    args:
      - /Users/admin/projects/hermes-n8n-mcp-plus/server.py
    enabled: true
    env:
      N8N_API_KEY: "${N8N_API_KEY}"
      N8N_API_URL: "http://localhost:5678/api/v1"

Die Einrückung ist wichtig. Sowohl n8n: als auch n8n_plus: müssen auf derselben Einrückungsebene direkt unter mcp_servers: stehen, ohne dass ein anderer Top-Level-Schlüssel den Block dazwischen unterbricht. Prüfe, dass die Datei korrekt geparst wird, bevor du neu lädst:

python3 -c "import yaml; d = yaml.safe_load(open('/Users/admin/.hermes/config.yaml')); print(list(d.get('mcp_servers', {}).keys()))"

Lade dann MCP in Hermes neu:

/reload-mcp

Oder über die Shell:

hermes mcp test n8n_plus

Die Tools registrieren sich mit dem Servernamen-Präfix, z. B. mcp__n8n_plus__create_workflow, mcp__n8n_plus__health, unterscheidbar von den mcp__n8n__*-Tools der ursprünglichen Brücke, falls beide parallel laufen.

Rauchtest außerhalb von Hermes

. .venv/bin/activate
python -m py_compile server.py
python -c "import server; print('imported OK')"
hermes mcp test n8n_plus

Wenn import server hängt oder einen ModuleNotFoundError: No module named 'mcp.server.fastmcp' wirft, überprüfe die mcp==1.29.0-Fixierung oben — das ist fast immer ein Problem der Abhängigkeitsversion, kein Code-Problem.

Verwendung der Schreib-Tools

Alle drei Schreib-Tools folgen demselben Muster, bei dem standardmäßig ein Dry-run ausgeführt wird. Beispielablauf für create_workflow:

Call mcp__n8n_plus__create_workflow with workflow={"name": "test", "nodes": [], "connections": {}} and confirm=false.

Gibt eine Vorschau zurück, keine Änderung:

{
  "ok": false,
  "error": "Dry run only. Set confirm=true to create the workflow.",
  "workflow_preview": { "name": "test", "nodes": [], "connections": {} }
}

Sobald die Vorschau richtig aussieht, führe sie erneut mit confirm=true aus, um den Workflow tatsächlich zu erstellen. Dasselbe Muster gilt für update_workflow (zeigt den aktuellen Zustand und den vorgeschlagenen Patch an) und delete_workflow (zeigt vor dem Löschen eine Export-Backup-Vorschau an).

Empfohlene Testreihenfolge für jede neue Umgebung: create_workflow, dann list_workflows, um zu bestätigen, dass es angekommen ist, dann update_workflow, dann delete_workflow — jeweils mit einem Wegwerf-Workflow und in jedem Schritt gegen die n8n-Oberfläche verifiziert.

Docker-Logs

container_logs ruft Docker über die Shell auf. Wenn der Benutzer, der Hermes ausführt, keinen Zugriff auf Docker hat, setze:

N8N_MCP_ALLOW_DOCKER_LOGS=false

Die übrigen API-Tools funktionieren weiterhin.

Hinweise für den Produktionseinsatz

• Halte n8n hinter deinem Reverse-Proxy an Loopback gebunden.

• Stelle diese MCP-Brücke nicht über Caddy-, nginx- oder Docker-Ports bereit.

• Rotiere n8n-API-Schlüssel, falls sie jemals in Chat-Logs, Terminals, CI-Ausgaben, Screenshots oder Issue-Trackern auftauchen.

• Sichere Workflows, bevor du sie veränderst. update_workflow und delete_workflow zeigen beide den Zustand vor der Bestätigung an, aber überprüfe die Vorschau immer selbst, bevor du confirm=true übergibst.

• Lockere die mcp==1.29.0-Fixierung in requirements.txt niemals, ohne zuvor gegen die MCPServer-v2-API zu testen.

Roadmap

• Migriere von FastMCP (v1.x) zu MCPServer (v2.x), sobald die v2-API stabil ist und das Toolset dieses Forks als kompatibel verifiziert wurde.

• Ziehe in Betracht, run_workflow als viertes Schreib-Tool für manuelle Auslöser hinzuzufügen.

Lizenz

MIT. Siehe LICENSE.