mcp-n8n-builder

mcp-n8n-builder

n8n ワークフローをプログラムで作成および管理するための Model Context Protocol（MCP）サーバーです。このサーバーは、n8n の REST API とやり取りするためのツールとリソースを提供し、AI アシスタントがユーザーの直接操作なしにワークフローを作成、変更、管理できるようにします。

特長

• 🔄 ワークフロー管理：ワークフローの作成、読み取り、更新、削除、有効化、無効化ができます
• 📊 実行管理：ワークフローの実行詳細を一覧表示、取得できます
• ✅ スキーマ検証：入力データと出力データの両方を Zod で包括的に検証します
• 🔍 ノード検証：エラーを防ぐため、ワークフロー作成前にノードタイプが n8n の利用可能なノードに含まれているかを検証します
• 🤔 スマートな候補提示：無効なノードが検出された場合、類似したノードタイプを提案します
• 🛠️ エラー処理：トラブルシューティングに役立つ詳細なエラーメッセージを提供します
• 📝 ドキュメント：すべてのツールとリソースについて詳しく説明します
• 🔍 検索とフィルター：名前、タグ、有効状態でワークフローを絞り込めます

⚠️ トークン消費に関する警告

n8n ワークフローの性質上、このツールは「トークンを大量に消費」します。

• N8N ワークフローは、ノード、接続、パラメーター、設定が入れ子になった複雑な JSON 構造です
• 単一のワークフローでも、表示または編集時に数千トークンを簡単に消費することがあります
• 重要なワークフロー情報を失わずに JSON 構造を有意に縮小することはできません
• LLM のコンテキストウィンドウには上限があり、複雑なワークフローは利用可能なコンテキストを超える場合があります

軽減策

このツールには、トークン使用量を減らすための最適化がいくつか実装されています。

• 詳細度の制御：完全な JSON の代わりに概要を表示するには、OUTPUT_VERBOSITY=concise（デフォルト）を使用します
• オブジェクトの簡略化：ワークフロー一覧には、必要なフィールド（id、name、status、node count）のみが表示されます
• ガイドの選択的な挿入：エラーメッセージには、構成ガイドの関連セクションのみが含まれます
• ツールごとの詳細度：verbosity パラメーターを使って、個々のツール呼び出しで詳細度を変更できます

推奨される使い方

• まずワークフローを一覧表示して、必要なものを特定します（トークン消費量が少ない）
• 可能な場合は、シンプルなワークフローを使用します
• 完全な JSON が必要な場合を除き、詳細度には concise を使用します
• 複雑なワークフローを小さな単位に分割して、管理しやすくします
• 大規模なワークフローを取得または編集する前に、トークン消費量を考慮します

設定

このサーバーの設定は、MCP クライアントを通じて行う必要があります。各環境での設定例を以下に示します。

Cline の設定

Cline の MCP 設定に以下を追加します。

{
	"mcpServers": {
		"n8n-workflow-builder": {
			"command": "npx",
			"args": ["-y", "mcp-n8n-builder"],
			"env": {
				"N8N_HOST": "http://localhost:5678/api/v1",
				"N8N_API_KEY": "your-n8n-api-key",
				"OUTPUT_VERBOSITY": "concise" // Options: 'concise' or 'full'
			}
		}
	}
}

WSL 環境での Claude Desktop の設定

WSL 環境では、Claude Desktop の設定に以下を追加します。

{
	"mcpServers": {
		"n8n-workflow-builder": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"N8N_HOST=http://localhost:5678/api/v1 N8N_API_KEY=your-n8n-api-key OUTPUT_VERBOSITY=concise npx -y mcp-n8n-builder"
			]
		}
	}
}

環境変数

環境変数を使ってサーバーを設定できます。

変数	説明	デフォルト
N8N_HOST	n8n API の URL	http://localhost:5678/api/v1
N8N_API_KEY	n8n 認証用の API キー	""
SERVER_NAME	MCP サーバーの名前	"n8n-workflow-builder"
SERVER_VERSION	MCP サーバーのバージョン	パッケージのバージョン
LOG_LEVEL	ログレベル	"info"
CACHE_ENABLED	キャッシュを有効化	false
CACHE_TTL	キャッシュの TTL（秒）	300
OUTPUT_VERBOSITY	出力の詳細度（concise または full）	"concise"

MCP ツール

ノード管理

• list_available_nodes：n8n インスタンスで利用可能なすべてのノードを一覧表示します。重要：ワークフローを作成または更新する前に、このツールを使用して、有効なノードタイプのみを使用するようにしてください。これにより、現在の n8n インスタンスに存在しないノードタイプを使用して発生するエラーを防げます。

ワークフロー管理

• list_workflows：n8n のすべてのワークフローを、ID、名前、ステータス、作成日、タグなどの基本情報とともに一覧表示します。アクティブ状態、タグ、名前で結果を絞り込めます。
• create_workflow：指定したノードと接続を使用して、n8n に新しいワークフローを作成します。割り当てられた ID とともに、作成されたワークフローを返します。すべてのノードタイプが n8n インスタンスに存在することを検証します。
• get_workflow：ID で指定したワークフローの完全な詳細を取得します。すべてのノード、接続、設定、メタデータが含まれます。
• update_workflow：既存のワークフローを新しい設定で更新します。変更する部分だけでなく、ワークフローの構造全体を指定する必要があります。すべてのノードタイプが n8n インスタンスに存在することを検証します。
• delete_workflow：ID で指定したワークフローを完全に削除します。この操作は取り消せません。
• activate_workflow：ID で指定したワークフローを有効化し、トリガーに基づいて自動実行できるようにします。
• deactivate_workflow：ID で指定したワークフローを無効化し、自動実行を停止します。

実行管理

• list_executions：ワークフローの実行履歴を、成功／失敗のステータス、所要時間、タイムスタンプなどの詳細とともに一覧表示します。ワークフロー ID やステータスで結果を絞り込んだり、取得件数を指定したりできます。
• get_execution：特定のワークフロー実行に関する詳細情報を取得します。実行時間、ステータス、各ステップで処理された全データを含めるかどうかを指定できます。

MCP リソース

• n8n://workflows：n8n のすべてのワークフローの一覧
• n8n://workflows/{id}：特定の n8n ワークフローの詳細
• n8n://executions/{id}：特定の n8n ワークフロー実行の詳細

開発

セットアップ

1. リポジトリをクローンします
2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

4. 開発モードで実行します：

npm run dev

公開

このプロジェクトでは、バージョン管理に changesets を使用しています。公開するには：

1. changeset を作成します：

npm changeset

2. パッケージのバージョンを更新します：

npm changeset version

3. npm に公開します：

npm release

貢献

皆さまからの貢献を歓迎します。お気軽にプルリクエストをお送りください。

ライセンス

MIT ライセンスの詳細については、LICENSE ファイルをご覧ください。

謝辞

• Model Context Protocol を基盤に構築されています
• n8n を活用しています