mcp-n8n

MCP n8n サーバー

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

環境変数は 2 つだけです。お使いのマシン上で（stdio）動作するほか、リモート HTTP サーバーとしても動作します。ホストアカウントは不要です。

---

🎯 トークンの最適化

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

最適化した点：

• 新しい n8n_list_workflows_summary エンドポイントにより、ワークフロー一覧表示時のトークンを 90% 削減
• フィールドのフィルタリング — 必要なデータだけをリクエスト
• スマートなデフォルト値 — クエリあたりの結果数を 100 件から 10～20 件に削減
• インテリジェントな警告 — トークンを大幅に消費する操作を事前に通知

詳しい使い方は TOKEN_OPTIMIZATION.md をご覧ください。

---

✨ 機能

🔄 ワークフロー管理

• 作成とデプロイ：自然言語の説明からワークフローを構築
• 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 インスタンスで「Settings」→「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 設定（Settings → Extensions → 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、メールの自動化
• コンテンツ：ブログの自動化、動画生成、SEO 最適化
• 人事／採用：履歴書のスクリーニング、候補者の情報収集
• 営業／CRM：リード獲得、コールドコールのパイプライン
• 金融：株式分析、請求書の情報抽出
• データスクレイピング：Google Maps、LinkedIn、Amazon、TikTok
• モニタリング：ウェブサイトの稼働状況、競合の追跡
• 生産性：カレンダー、Notion、スケジュール管理の自動化

実行（4 ツール）

• n8n_list_executions - ステータス、ワークフロー、プロジェクトで絞り込みます
• n8n_get_execution - 実行の詳細データ
• n8n_delete_execution - 実行記録を削除します
• n8n_retry_execution - 失敗した実行を再試行します
• n8n_debug_last_error - 最後のエラーが発生したノードとエラーメッセージ
• n8n_get_node_execution_data - 特定のノードを通過したデータ
• n8n_workflow_health - ワークフローごとの成功率、失敗数、実行時間

認証情報（4 ツール）

• n8n_create_credential - 新しい認証情報を追加します
• n8n_delete_credential - 認証情報を削除します（オーナーのみ）
• n8n_get_credential_schema - 必須フィールドを確認します
• n8n_transfer_credential - プロジェクト間で移動します

組織（19 ツール）

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

高度な機能（2 ツール）

• n8n_generate_audit - セキュリティ監査レポート
• n8n_pull_source_control - バージョン管理との統合

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

---

📚 ドキュメント

• クイックスタートガイド - 5 分で使い始められます
• サンプルとユースケース - 実際の自動化の例
• ノードリファレンス - ツールの詳細なドキュメント
• 変更履歴 - バージョン履歴と更新内容

---

🏗️ プロジェクト構成

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. まずテストする：本番環境で有効化する前に、ワークフローをテストします

---

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• n8n Community: community.n8n.io

---