Hermes n8n MCP Plus

Hermes Agent から n8n を管理するためのローカル stdio MCP ブリッジ — 書き込みツール対応版。

これは CyberSamuraiX/hermes-n8n-mcp のフォークで、元の読み取り専用/操作ツールセットに加えて create_workflow、update_workflow、delete_workflow を追加したものです。Hermes から n8n をパブリックインターネットに公開したり、Hermes の設定に API キーを埋め込んだりすることなく、n8n ワークフローを完全に管理できます。

機能

以下の MCP ツールを提供します:

• health — n8n API の到達可能性とオプションの Docker コンテナ状態を確認

• list_workflows — ワークフロー一覧を表示（アクティブ状態でフィルタリング可能）

• get_workflow — 機密フィールドをマスクしてワークフローを 1 件取得

• find_workflows — ワークフローのメタデータを検索

• list_executions — 最近の実行履歴を一覧表示

• get_execution — 実行詳細を 1 件取得（ペイロードデータはデフォルトでオフ）

• recent_failures — 最近の失敗/エラー実行を表示

• export_workflow — バックアップ/レビュー用にマスク済みワークフロー JSON をエクスポート

• activate_workflow — ワークフローを ID でアクティブ化

• deactivate_workflow — ワークフローを ID で非アクティブ化

• container_logs — オプションの Docker ログ（行レベルでマスク処理）

• create_workflow — JSON 定義から新しいワークフローを作成。デフォルトはドライラン。

• update_workflow — ID で既存ワークフローを更新（名前、ノード、接続、設定、タグ）。適用前に現在の状態をプレビュー。デフォルトはドライラン。

• delete_workflow — ID でワークフローを完全削除。削除前にエクスポートバックアップをプレビュー。デフォルトはドライラン。

3 つの書き込みツールはすべて、実際に変更を行うには明示的な confirm=true 引数が必要です。confirm=false（デフォルト）で呼び出すと、何が起こるかのプレビューを返し、n8n を変更する API 呼び出しは行いません。

Related MCP server: n8n-ops-mcp

セキュリティ体制

• stdio のみ。HTTP サーバーなし。公開ポートなし。

• API キーは環境変数またはローカルの dotenv ファイルから読み込み。

• .env は gitignore 対象。

• 設定例では REPLACE_ME を使用し、実際のキーは使用しない。

• ツールの応答では、認証情報、トークン、シークレット、パスワード、認可フィールドをマスク処理。

• get_execution では実行ペイロードデータはデフォルトで無効。

• ワークフローのアクティブ化/非アクティブ化、作成、更新、削除はすべて本番環境への変更操作。危険な武器として扱うこと。

• 書き込みツールはデフォルトでドライランプレビューを実行。呼び出し側が明示的に confirm=true を渡さない限り、作成・更新・削除は行われない。

• delete_workflow は、確認付き削除を実行する前に必ずワークフローのエクスポート/バックアッププレビューを取得する。

要件

• Python 3.10+

• ネイティブ MCP 対応の Hermes Agent

• n8n API キー

• Hermes を実行するマシンから到達可能な n8n（通常は http://127.0.0.1:5678）

重要な依存関係の固定: mcp==1.29.0

公式の mcp PyPI パッケージは 2026-07-28 に破壊的変更を含む v2.0.0 をリリースし、mcp.server.fastmcp を完全に削除しました（MCPServer に改名、モジュールパスを移動、httpx を httpx2 に交換、その他多数）。requirements.txt で mcp>=1.29.0 のような緩い制約を使用すると、pip install が 2.0.0 を解決してしまい、サーバーが次のエラーで起動時にクラッシュします:

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

このリポジトリでは mcp==1.29.0（v2 前の最後の安定版）をハードピンとして固定しています。これは下限ではなく固定です。コードベースが v2 の MCPServer API に移行するまで、この制約を緩めないでください。上記のエラーが発生した場合は、pip show mcp で確認してください — 2.0.0 以降が報告された場合は、次を実行してください:

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

インストール

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

インストール後、SDK バージョンが正しいことを確認してください:

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

n8n キーの保存

手動での方法:

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

REPLACE_ME を実際のキーに置き換えてください。実際のキーをコミットしないでください。

このフォークのツールは、dotenv ファイルだけでなく環境変数からも N8N_API_KEY / N8N_API_URL を直接読み取ります。そのため、~/.hermes/config.yaml から ${N8N_API_KEY} 補間を使って直接注入することもできます — 下記参照。

Hermes の設定

~/.hermes/config.yaml の mcp_servers の下にこれを追加してください。元の n8n ブリッジがすでに登録されている場合は、置き換えるのではなく、2 つ目の別エントリ（n8n_plus）として追加してください — これにより安全な読み取り専用フォールバックが維持されます:

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"

インデントは重要です。n8n: と n8n_plus: は両方とも mcp_servers: の直下で同じインデントレベルに配置し、間に他のトップレベルキーを挟まないでください。リロード前にファイルが正しく解析されることを確認してください:

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

その後、Hermes で MCP をリロードします:

/reload-mcp

またはシェルから:

hermes mcp test n8n_plus

ツールはサーバー名のプレフィックス付きで登録されます。例: mcp__n8n_plus__create_workflow、mcp__n8n_plus__health。両方を並行して実行している場合、元のブリッジの mcp__n8n__* ツールとは区別されます。

Hermes 外部でのスモークテスト

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

import server がハングするか、ModuleNotFoundError: No module named 'mcp.server.fastmcp' をスローした場合は、上記の mcp==1.29.0 の固定を再確認してください — これはほとんどの場合、コードの問題ではなく依存関係のバージョン問題です。

書き込みツールの使用方法

3 つの書き込みツールはすべて、同じデフォルト・ドライランパターンに従います。create_workflow のフロー例:

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

プレビューが返され、変更は行われません:

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

プレビューが問題なければ、confirm=true を付けて再実行すると実際に作成されます。同じパターンが update_workflow（現在の状態と提案されたパッチをプレビュー）と delete_workflow（削除前にエクスポートバックアップをプレビュー）にも適用されます。

新しい環境での推奨テスト順序: create_workflow → list_workflows で作成を確認 → update_workflow → delete_workflow — 各ステップで使い捨てワークフローを使用し、n8n UI で確認しながら進めてください。

Docker ログ

container_logs は Docker をシェルアウトして使用します。Hermes を実行するユーザーが Docker にアクセスできない場合は、次を設定してください:

N8N_MCP_ALLOW_DOCKER_LOGS=false

残りの API ツールは引き続き動作します。

本番環境での注意事項

• n8n はループバックにバインドしたまま、リバースプロキシの背後に配置してください。

• この MCP ブリッジを Caddy、nginx、Docker ポート経由で公開しないでください。

• n8n API キーがチャットログ、ターミナル、CI 出力、スクリーンショット、イシュートラッカーに漏れた場合は、すぐにローテーションしてください。

• ワークフローを変更する前にバックアップを取得してください。update_workflow と delete_workflow はどちらも確認前に状態をプレビューしますが、confirm=true を渡す前に必ず自分でプレビューを確認してください。

• requirements.txt の mcp==1.29.0 の固定は、MCPServer v2 API に対して事前にテストせずに緩めないでください。

ロードマップ

• v2 API が安定し、このフォークのツールセットが互換性検証された時点で、FastMCP（v1.x）から MCPServer（v2.x）へ移行する。

• 手動実行トリガー用の 4 つ目の書き込みツールとして run_workflow の追加を検討する。

ライセンス

MIT。LICENSE を参照。