Automatelab N8n

n8n-mcp

n8n 用の MCP サーバーです。Claude、Cursor、その他の AI エージェントに、ワークフローの生成、リンティング、実行失敗の診断、稼働中の n8n インスタンスの操作に役立つツールを提供します。

開発の背景

AutomateLab では n8n を日常的に利用していますが、LLM が同じような問題に何度も直面していました。インポートはできても実行時に失敗するワークフロー JSON、誤った接続タイプでつながれた AI Agent クラスター、どこを調べればよいかわからないままアイテムがひっそり消失する実行などです。n8n のカタログ全体をコンテキストに詰め込んでも解決しません。失敗の原因があまりにも見つけにくいためです（typeVersion の不一致、IF v1 のスキーマ、インポート後に維持されない認証情報など）。

そこで、焦点を絞った小さなサーバーを作りました。リンターで検出できる失敗パターン、ジェネレーターが従うべきクラスターのトポロジー、そしてエージェントだけでは実行できない診断を組み込みます。 元となる 9 つのツールを出力例とともに紹介した、リリース当初の手順については、automatelab.tech のリリース記事をご覧ください。

どこが違うのか

他の n8n MCP サーバー（特に czlonkowski/n8n-mcp）は、幅広さ、つまり 20 以上のツールと n8n のすべてのノードをインデックス化したコーパスで競っています。この分野は彼らに任せています。

このサーバーは、n8n のデバッグと初回実行の正確性に特化した MCP です。

• execution_explain が中核です。実行 JSON を貼り付けると、ノードごとの分析結果が返されます。0 個のアイテムを返したノード、未解決の ={{ ... }} 式、具体的なヒントを含むエラーメッセージなどを確認できます。これをうまく実現する他の MCP サーバーはありません。n8n コミュニティで最も多いデバッグ上の悩みである、ノード間でのデータのひそかな消失に対応します。
• workflow_generate は AI Agent のトポロジーにこだわり、適切な LangChain クラスターを生成します。ai_languageModel／ai_memory／ai_tool 接続を使います（サブノードは main 経由ではなく、エージェントに向かって上向きに接続します）。n8n 1.x に問題なくインポートできます。
• workflow_lint は見落とされやすい失敗を検出します。非推奨のノードタイプ（Function → Code、spreadsheetFile → convertToFile）、言語モデルが設定されていない AI Agent、IF v1 のスキーマ、webhookId がない Webhook、すべての接続タイプ（main だけではありません）における接続の不備などです。
• 5 つの REST ツール（N8N_API_URL と N8N_API_KEY の設定が必要）を使うと、ワークフローの一覧表示、取得、作成、有効化、実行情報の取得ができます。これにより、リンティングツールと説明ツールは、チャットに貼り付けた JSON だけでなく、稼働中のワークフローに対しても実行できます。

さらに、どのツールをいつ使うか、より詳しいコンテキストをどこから読み込むかをモデルに教える、ペアとなる エージェントスキル も用意しています（プロンプトが肥大化しないよう、内容は references/ に分割されています）。

ツール

ツール名はドット記法に従い、ナビゲート可能なツリーを構成します：node.*、workflow.*、execution.*。各ツールはoutputSchema（呼び出し側がレスポンスの型をチェックするため）とMCPのannotations（読み取り専用／破壊的／冪等／オープンワールドのヒント）を宣言します。

ステートレス（稼働中のn8nインスタンスなしで動作）：

ツール	用途
workflow_generate	平易な英語の説明 → ワークフローJSON。AIエージェントの意図を検出します。
node_scaffold	説明 → カスタムn8nパッケージ用の単一のINodeType TypeScriptファイル。
workflow_lint	ワークフローJSON → エラーと警告のリスト（20以上のルール）。
workflow_diff	2つのワークフロー → セマンティック差分（追加／削除／変更されたノード、接続、設定）。
execution_explain	失敗した実行のJSON → ヒント付きのノードごとの診断。
execution_replay	ワークフロー＋ノード → そのノードのみを実行する、自己完結型のリプレイ用ワークフロー。
execution_timeline	実行JSON → ノードごとのタイムライン表（開始、所要時間、入出力アイテム数、エラー）。

ライブインスタンス用（N8N_API_URL＋N8N_API_KEY環境変数が必要）：

ツール	用途
workflow_list	ワークフローをページネーションで取得します。アクティブ状態／タグ／名前で絞り込みます。
workflow_get	IDでワークフローを取得します。
workflow_create	ワークフローをPOSTします。読み取り専用フィールドを除去します。
workflow_activate	アクティブ状態をオン／オフに切り替えます。
execution_list	実行を参照します。完全な本文を取得するにはincludeData: trueを渡します。

v0.5.0の変更点。 3つの新しいツール：workflow_diff、execution_replay、execution_timeline。Lintに10個の新しいルールを追加（レート制限、認証情報のドリフト、式の陳腐化、コードサンドボックス、Webhookのテストパス、アクティブ状態のmanualTrigger、DSTスケジュールのリスク、無効化されているが接続済み、空のSet、HTTPメソッド／本文の不一致）。新しいランタイムポリシー環境変数：N8N_MCP_READ_ONLY、N8N_MCP_DISABLED_TOOLS、N8N_MCP_ALLOWED_WORKFLOW_IDS、N8N_MCP_ALLOWED_TAGS。DXTバンドル＋Dockerfile＋Render／Railway／Flyのデプロイ設定。

v0.4.0の破壊的変更。 ツール名をn8n_*（snake_case）からドット記法に変更しました。以前の名前を参照していたプロンプト、エージェントスキル、スクリプトを更新してください。

ランタイムポリシー（v0.5以降）

フォークせずにサーバーを制限できます。起動前に次の環境変数を設定してください：

環境変数	効果
N8N_MCP_READ_ONLY=1	workflow_create、workflow_activate、node_scaffoldを無効にします。
N8N_MCP_DISABLED_TOOLS=workflow_create,workflow_activate	これらのツール登録を完全にスキップします。
N8N_MCP_ALLOWED_WORKFLOW_IDS=abc,def	RESTツールは、リスト外のワークフローへの操作を拒否します。
N8N_MCP_ALLOWED_TAGS=prod,staging	workflow_listは、少なくとも1つのタグが付いたワークフローに絞り込みます。

MCPをジュニアエージェントに渡す場合や、顧客向けアシスタントの背後に接続する場合に便利です。

デプロイ

• Claude Desktopのワンクリック：dxt/manifest.jsonから.dxtバンドルをビルドします（dxt/README.mdを参照）。
• Docker：docker build -t n8n-mcp . && docker run --rm -i -e N8N_API_URL=... -e N8N_API_KEY=... n8n-mcp。
• Render：render.yamlを追加し、「New from Blueprint」をクリックします。
• Railway：railway.toml — リポジトリのルートでrailway upを実行します。
• Fly.io：fly.toml — fly launch --copy-configを実行します。

インストール

Node 20以降が必要です。

CLIツールとして

npm install -g @automatelab/n8n-mcp

GitHub Actionとして

n8n MCP GitHub Actionを使用すると、CI/CDパイプラインでワークフローのLint、実行の診断、ワークフローJSONの生成を行えます：

- uses: ratamaha-git/n8n-mcp@v1
  with:
    command: 'lint'
    workflow-json: ${{ env.WORKFLOW_JSON }}

例と公開の詳細については、ACTION.mdおよびGITHUB-ACTION-SETUP.mdを参照してください。

MCPホストを設定する

Cursor（~/.cursor/mcp.json）またはClaude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@automatelab/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n.example.com",
        "N8N_API_KEY": "n8n_..."
      }
    }
  }
}

envブロックは省略可能です。4つのステートレスツールは、これがなくても動作します。n8nでAPIキーを取得してください：Settings → API → Create API key。

MCPホストを再起動します。12個のドット記法ツール（workflow.*、node.*、execution.*）がMCPパネルに表示されます。

ツールの使用例

workflow_generate

workflow_generateを使って、StripeのWebhookからSlackメッセージを送信し、Google Sheetsに新しい行を追加するワークフローを作成します。

n8nの「ファイルからインポート」ダイアログにそのまま取り込めるワークフローJSONを返します。

execution_explain

n8nで失敗した実行の内容です。Slackノードが実行されないのはなぜですか？ [JSONを貼り付け]

次を返します：

WARNING [Filter] Returned 0 items. Downstream nodes will not execute.
  hint: Common causes: (1) IF/Switch routed to the other branch — check `parameters.conditions`. (2) Filter/Set node dropped everything — inspect its output explicitly.

INFO [Last node executed was "Filter". If the workflow stopped here unexpectedly, check its output items below.]

workflow_lint

このワークフローJSONをリントします。 [JSONを貼り付け]

次を返します：

ERROR [AI Agent] AI Agent has no `ai_languageModel` sub-node connected. Attach a chat model (e.g. lmChatOpenAi).
WARNING [Webhook] Webhook node has no `webhookId`. n8n auto-generates one on import, so the production URL will change.
WARNING [LegacyFunction] Node type "n8n-nodes-base.function" is deprecated. Use "n8n-nodes-base.code".

または no issues found。

例

examples/ ディレクトリには、すぐにインポートできるワークフローが2つ含まれています。

• workflow-stripe-to-slack.json - StripeのWebhookからSlackとGoogle Sheetsに処理を分岐します。
• workflow-rss-to-discord.json - RSSフィードのトリガーにより、新しい項目をDiscordチャンネルに投稿します。

n8nの**「ファイルからインポート」**ダイアログから、どちらかをインポートしてください。

開発

git clone https://github.com/ratamaha-git/n8n-mcp
cd n8n-mcp
npm install
npm run build
npm run smoke

npm run smoke は --smoke フラグを指定してサーバーを起動し、登録済みのツールを一覧表示してから、stdioにバインドせずに終了します。CIや初回実行時の確認に便利です。

ライセンス

MITです。LICENSE を参照してください。

---

AutomateLabが開発しました。

メンテナンスと検証

解釈上の制限、該当する場合の現行のツール名、再現可能な検証については、メンテナンスガイドを参照してください。