MCP n8n Server

Cursor または Claude から n8n を操作・構築 — インスタンスの管理（ユーザー、プロジェクト、実行、監査）と、完全なビルダーループ：公式 n8n パッケージから抽出した実パラメータスキーマ付き 560 ノードのカタログ、保存前の検証、自動修復、ロールバックと差分付きスナップショット、ノード単位の実行デバッグ、ヘルスレポート、インスタンス全体のバックアップ。

環境変数は 2 つだけ。お使いのマシン上（stdio）またはリモート HTTP サーバーとして実行できます。ホスト型アカウントは不要です。

🎯 トークン最適化

このサーバーはトークン消費を最小化するように最適化されており、MCP サーバーの最大の問題の 1 つである API トークンの過剰使用に対処します。

最適化した内容:

• 新しい n8n_list_workflows_summary エンドポイントによるワークフロー一覧のトークン 90% 削減

• フィールドフィルタリング - 必要なデータのみをリクエスト

• スマートデフォルト - クエリあたりの結果を 100 件から 10〜20 件に削減

• インテリジェント警告 - 操作が大量のトークンを消費するときにアラート

詳細な使用方法については TOKEN_OPTIMIZATION.md を参照してください。

Related MCP server: n8n Workflow Builder

✨ 機能

🔄 ワークフロー管理

• 作成とデプロイ: 自然言語の説明からワークフローを構築

• CRUD 操作: ライフサイクル全体の管理（作成、読み取り、更新、削除）

• アクティベーション制御: 必要に応じてワークフローを有効/無効化

• プロジェクト転送: プロジェクト間でワークフローをシームレスに移動

• タグ管理: カスタムタグでワークフローを整理

📊 実行モニタリング

• リアルタイム追跡: 高度なフィルターでワークフロー実行を監視

• 詳細なインサイト: 完全な実行データとログにアクセス

• エラーリカバリ: 失敗した実行を自動的に再試行

• クリーンアップツール: 実行履歴を効率的に管理

🔐 認証情報管理

• 安全な作成: あらゆるサービスの認証情報を追加

• スキーマ検出: 認証情報タイプに必要なフィールドを自動検出

• プロジェクト分離: プロジェクト間で認証情報を安全に転送

• タイプサポート: すべての n8n 認証情報タイプに対応

🧱 ワークフロービルダー

• 完全なノードカタログ — 実スキーマ付き 560 ノード: n8n-nodes-base と @n8n/n8n-nodes-langchain から直接抽出（型、許可オプション、表示条件、認証情報、最新の typeVersion を含むパラメータ）。CI により毎週再生成。n8n_search_nodes で検索、n8n_get_node で詳細確認

• 実際の検証: n8n_validate_workflow は実スキーマに照らしてチェック — 存在しないノードタイプ、必須パラメータの欠落（条件付き必須を含む）、不正なオプション値、誤った typeVersion、壊れた接続 — 保存/アクティベーション前に

• 式のリンティング: = プレフィックスが欠落した {{ }} 式や、ワークフロー内に存在しないノードへの参照を検出

• 自動修復: n8n_autofix_workflow は欠落した typeVersion/位置、重複名、ぶら下がり接続、式プレフィックスを修正 — まずプレビューし、スナップショット付きで適用

• 外科的編集: n8n_update_workflow_partial はフロー全体を書き換えずにノードと接続を追加/削除

• 公開テンプレート: n8n.io から検索・インポート（n8n_search_public_templates、n8n_import_public_template）に加え、フォールバックとして 100 のバンドルテンプレート

• ガイド付きプロンプト: MCP プロンプト build-workflow と fix-workflow は、あらゆるエージェントをビルド/検証/テスト/修復の完全なループへ導きます

🔬 詳細デバッグとヘルス

• ノード単位の実行データ: n8n_get_node_execution_data は、実行全体をダウンロードすることなく、1 つのノードを通過したデータ（ステータス、アイテム数、出力サンプル、エラー詳細）を正確に表示

• デバッグループ: n8n_debug_last_error は最後のエラーから失敗ノードとメッセージを返します

• ヘルスレポート: n8n_workflow_health は最近の実行からワークフローごとの成功率、失敗数、平均所要時間、最終失敗日時を計算し、悪い順に並べます

🛡️ セーフティネットと実テスト

• 自動スナップショット: 更新、部分編集、自動修復、削除の前に、以前の状態がローカルに保存されます（~/.mcp-n8n/snapshots、N8N_SNAPSHOT_DIR で設定可能）

• ロールバック: n8n_rollback_workflow は任意のスナップショットを復元 — 削除されたワークフローの再作成も可能（recreate=true）

• 差分: n8n_diff_workflow_snapshot はロールバックを決定する前に、スナップショットと現在の状態を比較（追加/削除/変更されたノード、変更されたパラメータ、接続の変更）

• インスタンス全体のバックアップ: n8n_export_all_workflows はすべてのワークフローを JSON ファイルとして保存し、n8n_import_workflows で復元

• エンドツーエンドテスト: n8n_trigger_webhook はインスタンス上の Webhook トリガーワークフローを呼び出し、実際の HTTP レスポンスを返すため、エージェントはフローが実際に動作することを確認できます

🎯 バンドルテンプレート

• n8n.io にアクセスしたくない場合に備えた、キーワードマッチング付きのローカルスターターポイント 100 件

🏗️ 組織と管理

• タグ: リソースの分類と整理

• 変数: 一元管理された環境変数管理

• プロジェクト: マルチテナントプロジェクト対応

• ユーザーと権限: 完全なアクセス制御管理

• 監査ログ: セキュリティとコンプライアンスレポートの生成

🚀 クイックスタート

npm によるインストール（推奨）

これが最も簡単な始め方です:

npm install -g mcp-n8n

設定

1. n8n API 認証情報を取得:

   • n8n インスタンス → 設定 → n8n API に移動

   • 新しい API キーを生成

2. Claude Desktop を設定:

~/Library/Application Support/Claude/claude_desktop_config.json（Mac/Linux）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加:

オプション A - グローバルインストールを使用（npm install -g mcp-n8n を実行した場合）:

{
  "mcpServers": {
    "n8n": {
      "command": "mcp-n8n",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "N8N_TOOLSETS": "all"
      }
    }
  }
}

N8N_TOOLSETS はオプションです（デフォルトは all）。ユーザー/プロジェクト管理ツールなしで操作＋作成を行いたい場合は core,builder を使用します。インスタンス管理のみの場合は admin を使用します。

リモート HTTP モード（オプション）

デフォルトではサーバーは stdio（ローカル）で通信します。共有リモートサーバー（Docker や VPS など）として実行するには、ポートを設定します:

N8N_BASE_URL=https://your-n8n-instance.com \
N8N_API_KEY=your-api-key \
N8N_MCP_HTTP_PORT=3000 \
N8N_MCP_HTTP_TOKEN=some-strong-secret \
mcp-n8n

これにより、ポート 3000 でストリーミング可能な HTTP 上に MCP プロトコルと GET /health エンドポイントが公開されます。N8N_MCP_HTTP_TOKEN の設定を強く推奨します。設定すると、すべてのリクエストに Authorization: Bearer <token> を含める必要があります。ストリーミング可能な HTTP をサポートする任意の MCP クライアントを、そのヘッダー付きで http://your-host:3000 に接続します。

オプション B - npx を使用（インストール不要、常に最新版）:

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

3. Cursor を設定:

Cursor の MCP 設定に追加（設定 → 拡張機能 → MCP）:

推奨 - npx を使用（常に最新版を使用）:

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

注: Cursor は MCP サーバーに npx を使用する必要があります。-y フラグはプロンプトなしでパッケージを自動的にインストール/更新します。

オプション C - Docker:

docker build -t mcp-n8n .

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_BASE_URL", "-e", "N8N_API_KEY",
        "-v", "mcp-n8n-data:/data",
        "mcp-n8n"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

/data ボリュームは実行間でワークフロースナップショットを保持します。

4. Claude Desktop または Cursor を再起動

💬 使用例

設定後は、自然言語で n8n と対話できます:

ワークフローの作成

"Create a workflow that monitors my Gmail inbox and sends
Slack notifications for important emails"

"Build a daily report workflow that pulls data from my database,
generates charts, and emails them to my team"

テンプレートの使用

"I need a WhatsApp chatbot with AI for customer support"
→ Automatically creates workflow from "WhatsApp AI Response Bot" template

"Create an automated stock analysis workflow"
→ Uses "Automated Stock Analysis with GPT-4" template

ワークフローの管理

"Show me all active workflows in the production project"
→ Uses n8n_list_workflows_summary for efficient token usage

"Show me the details of workflow abc123"
→ Uses n8n_get_workflow to fetch complete details only when needed

"Deactivate the 'Daily Backup' workflow"

"What went wrong with execution abc123?"

モニタリングとデバッグ

"Show me the last 10 failed executions"

"Retry all failed executions from workflow xyz456"

"Delete all successful executions older than 30 days"

🛠️ 利用可能なツール

• n8n_create_workflow - 新しいワークフローを作成（最初に検証）

• n8n_list_workflows_summary - トークン効率の良い一覧表示

• n8n_list_workflows - オプションのフィールドフィルタリング付きの完全な詳細

• n8n_get_workflow - 完全なワークフロー JSON

• n8n_update_workflow - フィールドを置換（省略したフィールドは現在の値を維持）

• n8n_update_workflow_partial - 外科的編集: ノードと接続の追加/削除

• n8n_delete_workflow - ワークフローを完全に削除

• n8n_activate_workflow / n8n_deactivate_workflow

• n8n_transfer_workflow / タグツール

• n8n_list_workflow_snapshots - このサーバーを通じて行われたすべての変更のローカル履歴

• n8n_rollback_workflow - 以前のバージョンを復元、または削除されたワークフローを再作成

• n8n_diff_workflow_snapshot - ロールバック前にスナップショットと現在の状態を比較

• n8n_trigger_webhook - Webhook ワークフローを呼び出して実際のレスポンスを取得

• n8n_export_all_workflows / n8n_import_workflows - インスタンス全体のバックアップと復元

• n8n_search_nodes / n8n_get_node - 完全なカタログ: 実パラメータスキーマ付き 560 ノード

• n8n_validate_workflow - 保存/アクティベーション前に JSON を実スキーマに照らしてチェック

• n8n_autofix_workflow - 機械的な修復: typeVersion、位置、重複、ぶら下がり接続、式プレフィックス

• n8n_search_public_templates / n8n_import_public_template - 公式 n8n.io ライブラリ

• n8n_list_workflow_templates / n8n_get_workflow_template / n8n_create_workflow_from_template - バンドルテンプレート

13 カテゴリにわたる 100 のバンドルテンプレート:

• E コマース: Shopify 自動化、WooCommerce サポートエージェント

• ソーシャルメディア: Instagram、TikTok、LinkedIn、Twitter 自動化

• AI/チャット: チャットボット、AI エージェント、音声アシスタント

• コミュニケーション: WhatsApp、Telegram、Email 自動化

• コンテンツ: ブログ自動化、動画生成、SEO 最適化

• HR/採用: 履歴書スクリーニング、候補者ソーシング

• 営業/CRM: リードジェネレーション、コールドコーリングパイプライン

• ファイナンス: 株価分析、請求書抽出

• データスクレイピング: Google Maps、LinkedIn、Amazon、TikTok

• モニタリング: Web サイトの稼働時間、競合他社の追跡

• 生産性: カレンダー、Notion、スケジュール自動化

• n8n_list_executions - ステータス、ワークフロー、プロジェクトでフィルタリング

• n8n_get_execution - 詳細な実行データ

• n8n_delete_execution - 実行レコードを削除

• n8n_retry_execution - 失敗した実行を再試行

• n8n_debug_last_error - 最後のエラーから失敗ノード＋メッセージ

• n8n_get_node_execution_data - 特定の 1 つのノードを通過したデータ

• n8n_workflow_health - ワークフローごとの成功率、失敗数、所要時間

• n8n_create_credential - 新しい認証情報を追加

• n8n_delete_credential - 認証情報を削除（所有者のみ）

• n8n_get_credential_schema - 必須フィールドを検出

• n8n_transfer_credential - プロジェクト間で移動

タグ: 作成、一覧、取得、更新、削除 変数: 作成、一覧、更新、削除 ユーザー: 一覧、作成、取得、削除、ロール変更 プロジェクト: 作成、一覧、更新、削除、ユーザー管理

• n8n_generate_audit - セキュリティ監査レポート

• n8n_pull_source_control - バージョン管理統合

デフォルトでは 61 ツール（N8N_TOOLSETS=all）。core,builder は 28 を公開。さらに MCP プロンプト 2 つ（build-workflow、fix-workflow）。

📚 ドキュメント

• Quick Start Guide - 5 分で開始

• Examples & Use Cases - 実際の自動化の例

• Node Reference - 詳細なツールドキュメント

• Changelog - バージョン履歴と更新情報

🏗️ プロジェクト構造

mcp-n8n/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── n8n-client.ts     # n8n API client
│   └── types.ts          # TypeScript definitions
├── examples/
│   ├── templates-metadata.json
│   └── *.json            # Pre-built workflow templates
├── dist/                 # Compiled output
├── QUICKSTART.md         # Quick start guide
├── EXAMPLES.md           # Usage examples
├── NODE_REFERENCE.md     # API documentation
└── package.json

🔧 開発

ローカルインストール（開発用）

貢献したい場合やローカルの変更をテストしたい場合:

1. セットアップ

# Clone repository
git clone https://github.com/leonardosepulvedat/mcp-n8n.git
cd mcp-n8n

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

2. ローカルビルドでの設定

Claude Desktopの場合、~/Library/Application Support/Claude/claude_desktop_config.json に追加します:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursorの場合、MCP設定に追加します:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

重要: /absolute/path/to/mcp-n8n/ を、クローンしたリポジトリの実際の絶対パスに置き換えてください（例: /Users/yourname/projects/mcp-n8n/）。

3. テスト

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
node dist/index.js

実行方法

メインスクリプトを実行するには、次のコマンドを実行します:

python main.py

テスト方法

テストを実行するには、次のコマンドを実行します:

pytest test_main.py

📋 要件

• Node.js: 20以上

• n8nインスタンス: セルフホストまたはn8n Cloud（有料プラン）

• n8n APIキー: 認証に必要

• AI IDE: MCP対応のClaude DesktopまたはCursor

n8nの要件

• セルフホスト: 全APIアクセス ✅

• n8n Cloud: APIアクセスには有料プランが必要

• バージョン: n8n v1.0.0+ と互換性あり

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送ってください。

1. リポジトリをフォークする

2. フィーチャーブランチを作成する（git checkout -b feature/AmazingFeature）

3. 変更をコミットする（git commit -m 'Add some AmazingFeature'）

4. ブランチにプッシュする（git push origin feature/AmazingFeature）

5. プルリクエストを開く

📝 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細はLICENSEファイルを参照してください。

🙏 謝辞

• n8n - ワークフロー自動化プラットフォーム

• Anthropic - ClaudeおよびModel Context Protocol

• Cursor - AI搭載コードエディタ

🔗 リソース

• n8n APIドキュメント

• Model Context Protocol

• n8nコミュニティ

• MCPサーバーレジストリ

⚠️ 重要な注意事項

APIアクセス

• n8n CloudでAPIにアクセスするには有料プランが必要です

• セルフホストのn8nは全プランで全APIアクセスが可能です

• 一部の操作にはオーナー/管理者権限が必要です

セキュリティ

• 認証情報を含む.envファイルをコミットしないでください

• 機密データには環境変数を使用してください

• APIキーはn8nインスタンスへの完全なアクセスを許可します

• セキュリティのため、APIキーを定期的にローテーションしてください

レート制限

• n8n APIのレート制限を尊重してください

• 大量の結果セットにはページネーションを使用してください

• レート制限応答に対するエラーハンドリングを実装してください

🐛 トラブルシューティング

接続の問題

問題: 「n8n APIに接続できません」

• N8N_BASE_URLが正しく、アクセス可能であることを確認してください

• APIキーが有効であることを確認してください

• n8nインスタンスが実行中であることを確認してください

権限エラー

問題: 「権限が不十分です」

• 一部の操作にはオーナー/管理者ロールが必要です

• ユーザーに適切な権限があることを確認してください

• プロジェクトレベルのアクセス権を確認してください

テンプレートの問題

問題: 「テンプレートが見つかりません」

• examples/ディレクトリが存在することを確認してください

• templates-metadata.jsonが存在することを確認してください

• テンプレートファイルの参照が正しいことを確認してください

💡 ヒントとベストプラクティス

1. テンプレートから始める: 既製のテンプレートを出発点として使用する

2. タグを使用する: タグでワークフローを整理して管理を容易にする

3. 実行を監視する: 失敗した実行を定期的に確認する

4. クリーンアップ: スペースを節約するために古い実行データを削除する

5. バージョン管理: n8nの組み込みバージョン管理機能を使用する

6. 先にテスト: 本番環境で有効化する前にワークフローをテストする

📧 サポート

• 問題: GitHub Issues

• ディスカッション: GitHub Discussions

• n8nコミュニティ: community.n8n.io

⬆ トップに戻る