n8n Pro MCP

n8n Pro MCP ⚙️

キューモードを含むセルフホスト版 n8n のインスタンス全体を、Model Context Protocol 経由で管理します。ワークフロー、実行、タグ、認証情報、変数、プロジェクト、ユーザー、セキュリティ監査、ソース管理、ヘルスモニタリングをカバーする 51 個のツールを備えています。

n8n-pro-mcp は、公式の n8n public API v1 を介して、Claude Code、Claude Desktop、Cursor、または任意の MCP クライアントを n8n インスタンスに接続します。カーソルによるページネーションの自動処理、読み取り時の指数バックオフによる再試行（書き込みと Webhook 呼び出しは副作用の重複を防ぐため再試行されません）、さらに従来の n8n のよくあるミス（不正な {{ }} 式、.body を使わずにアクセスされる Webhook データ、return [{json: {...}}] がない Code ノード）をインスタンスに反映する前に検出するオフラインのワークフロー検証機能を備えています。

この MCP サーバーを選ぶ理由

• キューモードを第一級にサポート — list_running_executions（キューのリアルタイム表示）、get_execution_stats（ワークフローごとの成功率と平均所要時間）、check_health（healthz、readiness、API 認証）は、ワーカーと Webhook プロセッサーを備えた EXECUTIONS_MODE=queue で動作するインスタンス向けに構築されています。N8N_WEBHOOK_BASE_URL を使うと、Webhook 呼び出しの送信先を専用の Webhook プロセッサーにできます。
• API v1 を網羅 — 通常のワークフロー／実行の CRUD に加え、タグ、変数、プロジェクト、ユーザー、ソース管理、プロジェクト間の転送にも対応しています。
• オフライン検証を内蔵 — validate_workflow_json は、API を呼び出さずに構造、接続の整合性、孤立ノード、式の構文、Webhook の .body アクセス、Code ノードの戻り値の形式、ハードコードされたシークレットを検査します。create_workflow／update_workflow は検証を自動実行し、無効なペイロードを拒否します。
• 安全な部分更新 — update_workflow は現在のワークフローを取得し、渡された内容だけをマージして、読み取り専用フィールドを除外します。そのため、不完全な PUT を送信してノードを失うことはありません。
• 名前でタグを指定 — set_workflow_tags はタグ名を受け付け、不足しているタグを作成します。ID を手動で管理する必要はありません。
• 生の API にはない運用向け機能 — summarize_execution_error（巨大な JSON ダンプではなく、失敗したノードとエラーだけを表示）、prune_executions（ドライラン付きの一括クリーンアップ）、wait_for_execution（終了状態までポーリング）、clone_workflow、set_workflows_active_by_tag（タグベースのキルスイッチ）を利用できます。

インストール

npm install -g n8n-pro-mcp     # or use npx, no install needed

ソースから実行する場合：

git clone https://github.com/helbertparanhos/n8n-pro-mcp.git && cd n8n-pro-mcp
npm install
npm run build

ソースから実行する場合は、.env.example をプロジェクトのルートにある .env にコピーできます。サーバーは作業ディレクトリではなく、パッケージのルートから読み込みます。npx でインストールした場合は、代わりに MCP クライアントの設定で変数を指定してください（.env ファイルは npx のキャッシュから読み込まれません）。

設定

変数	必須	説明
N8N_API_URL	✅	インスタンスのベース URL（例：https://n8n.yourdomain.com）。/api/v1 のサフィックスは付けません
N8N_API_KEY	✅	n8n → Settings → n8n API → Create API key で取得する API キー
N8N_WEBHOOK_BASE_URL	—	Webhook 呼び出し用の個別のベース URL（専用 Webhook プロセッサーを使用するキューモードの場合）
N8N_API_TIMEOUT_MS	—	リクエストごとのタイムアウト（ミリ秒、デフォルトは 30000）
N8N_MAX_RETRIES	—	429／5xx／ネットワークエラー時の再試行回数。GET リクエストにのみ適用され、書き込みや Webhook 呼び出しには適用されません（デフォルトは 3、0 で無効化）

Claude Code

claude mcp add n8n-pro --env N8N_API_URL=https://n8n.yourdomain.com --env N8N_API_KEY=your-key -- npx -y n8n-pro-mcp

または、.claude/settings.json／.mcp.json に設定します：

{
  "mcpServers": {
    "n8n-pro": {
      "command": "npx",
      "args": ["-y", "n8n-pro-mcp"],
      "env": {
        "N8N_API_URL": "https://n8n.yourdomain.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "n8n-pro": {
      "command": "npx",
      "args": ["-y", "n8n-pro-mcp"],
      "env": {
        "N8N_API_URL": "https://n8n.yourdomain.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Cursor の MCP 設定（.cursor/mcp.json）に同じ JSON ブロックを指定します。

ツール（51）

ワークフロー（12）

ツール	説明
list_workflows	フィルター（active、tags、project、name）と自動ページネーションに対応した一覧表示
get_workflow	1 つのワークフローの完全な JSON または簡潔な概要を取得
create_workflow	JSON から作成し、オフライン検証を自動実行
update_workflow	部分更新 — 取得、マージ、検証、PUT
delete_workflow	完全に削除
activate_workflow / deactivate_workflow	トリガーの有効／無効を切り替え
transfer_workflow	プロジェクト間で移動
search_workflows	名前、ノード名、ノードタイプを対象とした全文検索
clone_workflow	ワークフローを非アクティブなコピーとして複製
set_workflows_active_by_tag	ドライラン付きで、タグに基づいて一括で有効化／無効化
validate_workflow_json	API を呼び出さないオフライン検証

実行（10）

ツール	説明
list_executions	ステータス／ワークフロー／プロジェクトで絞り込み、実行時間を表示します
get_execution	デバッグ用に、概要またはノード単位の詳細な実行データを取得します
delete_execution	実行記録を削除します
retry_execution	失敗または停止した実行を再試行します
list_running_executions	キューモードのライブビューで、実行中／キュー待ちの実行を表示します
run_webhook	本番用またはテスト用の Webhook でワークフローをトリガーします
wait_for_execution	実行が終了状態になるまでポーリングします
summarize_execution_error	失敗したノードとエラーメッセージのみを表示し、巨大な JSON ダンプは出力しません
prune_executions	古い実行記録を一括削除します。デフォルトではドライランです
get_execution_stats	サンプルにおけるワークフローごとの成功率と平均実行時間を表示します

タグ（6）

list_tags、create_tag、update_tag、delete_tag、get_workflow_tags、set_workflow_tags（名前で指定し、存在しないタグは自動作成します）。

認証情報（4）

create_credential、delete_credential、get_credential_schema、transfer_credential。シークレットは書き込み専用です。n8n API が認証情報のデータを返すことはありません。

変数（4）

list_variables、create_variable、update_variable、delete_variable（ライセンスが必要な機能です）。

プロジェクト（7）

list_projects、create_project、update_project、delete_projectに加え、メンバー管理用のadd_user_to_project、remove_user_from_project、change_user_project_role（ライセンスが必要な機能です）。

ユーザー（5）

list_users、get_user、create_user（招待）、delete_user、change_user_role。

システム（3）

ツール	説明
check_health	healthz、readiness（DB）、API 認証を確認し、平易な言葉で概要を表示します
generate_audit	n8n 組み込みのセキュリティ監査を実行します（認証情報、データベース、ノード、ファイルシステム、インスタンス）
pull_source_control	接続済みの Git リポジトリからプルします

キューモードの運用手順

EXECUTIONS_MODE=queue（メインプロセス＋ワーカー＋Redis）の場合：

1. check_health — メインプロセスと DB が稼働していることを確認します。
2. list_running_executions — 現在実際に進行中の実行を確認します。古いstartedAt値を持つ項目が増え続ける場合は、ワーカーが不足しているか、停止していることを示します。
3. get_execution_stats — 失敗または処理が遅いワークフローを確認します。成功率が低い順に表示されます。
4. N8N_WEBHOOK_BASE_URLがWebhookプロセッサーを指すよう設定してrun_webhookを実行し、本番の取り込み経路をエンドツーエンドでテストします。

開発

npm test             # build + unit tests (validation rules, client helpers, .env parser)
npm run watch        # incremental compile
npm run inspector    # interactive testing with @modelcontextprotocol/inspector

CI（GitHub Actions）では、プッシュと PR のたびにビルド、テスト、npm auditを実行します。

要件

• Node.js ≥ 18
• パブリック API が有効で（N8N_PUBLIC_API_DISABLEDが設定されていない）、API キーを持つ n8n インスタンス
• 変数、プロジェクト、ソース管理のツールを利用するには、対応する n8n のライセンス機能が必要です

👤 作者

**Strat AcademyのHelbert Paranhos**が作成しました。

このプロジェクトがお役に立ちましたら、リポジトリにスター ⭐ を付けて、AI 自動化ツールの最新情報を得るために**Strat Academy**をフォローしてください。

📄 ライセンス

MIT © Helbert Paranhos / Strat Academy — 詳細はLICENSEをご覧ください。