n8n AI Agent with Local MCP Integration (Docker + npx)

ローカル MCP 統合を使用する n8n AI エージェント（Docker + npx）

このリポジトリには、Docker でローカル実行する n8n インスタンスに Model Context Protocol（MCP）を統合し、AI エージェントが永続的なサーバーのインストールを必要とせずに、ウェブ検索などの外部ツールを動的に検出して使用できることを示す n8n ワークフローが含まれています。

この方法では、n8n の認証情報内で npx コマンドを使用し、MCP サーバーをその場で実行します。

主なコンセプト

• n8n AI Agent： LLM と利用可能なツールを使用して、推論、計画、タスクの実行ができる、n8n の強力なノードです。
• Model Context Protocol（MCP）： n8n AI Agent で使用されるものなど、AI モデルと外部ツール、データソース、API との通信を簡素化するために設計されたオープン標準です。ユニバーサルな翻訳機のような役割を果たします。
• npx 方式： npm レジストリの Node.js パッケージ（MCP サーバーなど）を永続的にインストールせずに実行できます。これを n8n のコマンドライン認証情報内で利用します。
• Docker： n8n をローカルで、分離されたコンテナー環境内で実行するために使用します。

目標

このワークフローの主な目標は、次の内容を紹介することです。

1. AI エージェントのツール使用に必要なフラグ（N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE）を有効にして、Docker 経由で n8n をローカル実行する。
2. コミュニティノード n8n-nodes-mcp をインストールして使用する。
3. npx を使用して MCP サーバー（例：Brave Search）を動的に実行するよう、n8n の認証情報を設定する。
4. 次のことができる n8n AI Agent ワークフローを構築する。
   • MCP 経由で利用可能なツールを検出する（List Tools）。
   • ユーザーのクエリとツールの説明／スキーマに基づいて、適切なツールを適切に選択する。
   • AI モデルが決定したパラメーターを使用して、MCP 経由で選択したツールを実行する（Execute Tool）。

前提条件

• Docker： ローカルマシンにインストールされ、実行されていること。Docker のインストールガイド
• Node.js と npm： トラブルシューティングへの備えや、npx を利用可能にするために推奨します。Node.js のインストールガイド
• n8n の基本知識： ワークフローの作成、ノードの追加、認証情報の設定に慣れていること。
• （任意）API キー： 認証が必要な MCP サーバー（Brave Search など）を使用する場合は、対応する API キーが必要です。

セットアップ手順

環境とワークフローを実行するには、次の手順に従ってください。

手順 1：Docker 経由で n8n をローカル実行する（ツール使用を有効にする）

ターミナルまたはコマンドプロンプトを開き、次の Docker コマンドを実行します。

docker run -it --rm --name n8n -p 5678:5678 \
-v n8n_data:/home/node/.n8n \
-e N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true \
docker.n8n.io/n8nio/n8n

• -p 5678:5678：コンテナーのポート 5678 を、ローカルマシンのポート 5678 にマッピングします。
• -v n8n_data:/home/node/.n8n：n8n のワークフローとデータを永続化するため、n8n_data という名前の Docker ボリュームを作成します。
• -e N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true：重要なフラグです！ この環境変数により、AI Agent ノードがコミュニティノード（MCP Client など）を実行可能なツールとして扱えるようになります。
• --rm：コンテナーの停止時に、自動的にコンテナーを削除します。
• -it：コンテナーを対話形式で実行します。

n8n の起動を待ちます。ブラウザーで http://localhost:5678 にアクセスできます。

手順 2：n8n MCP コミュニティノードをインストールする

1. n8n UI（http://localhost:5678）で、Settings > Community Nodes に移動します。
2. Install をクリックします。
3. 検索ボックスに n8n-nodes-mcp と入力します。
4. コミュニティノードに伴うリスクを確認し、同意します。
5. Install をクリックします。

ステップ 3：MCP クライアントの認証情報を設定する（npx を使用）

この例では、Brave Search MCP サーバーを使用します。各サーバーの npx コマンドを確認すれば、他のサーバーにも応用できます。

1. 使用する MCP サーバーの npx コマンドを確認します。Brave Search の場合は、npx run -y @modelcontextprotocol/server-brave-search です。
2. n8n ワークフローのキャンバスで、MCP Client ノードを追加します（コミュニティノードのセクションから選択します）。
3. ノードのパラメーターで、Credential to connect with のドロップダウンをクリックし、Create New Credential を選択します。
4. 認証情報を設定します。
   • Connect using: Command Line (STDIO)
   • Command: npx
   • Arguments: run -y @modelcontextprotocol/server-brave-search（または、選択したサーバー用の引数）
   • Environments:（任意ですが、認証が必要なサーバーでは必須です）
     • Add Environment Variable をクリックします。
     • Name: BRAVE_API_KEY（または、サーバーが想定する変数名）
     • Value: YOUR_BRAVE_SEARCH_API_KEY_HERE（実際のキーに置き換えてください）
   • Credential Name: 内容がわかる名前を付けます（例：MCP Brave Search (npx)）
5. Save をクリックします。

ワークフローの説明

このリポジトリに用意されているワークフローの JSON ファイルを n8n インスタンスにインポートします。ワークフローは、次の主要なノードで構成されています。

1. When chat message received (Chat Trigger)： n8n のチャットインターフェースからメッセージが送信されると、ワークフローを開始します。
2. AI Agent： 中核となるオーケストレーターです。
   • Chat Model： LLM（例：Groq Chat Model、OpenAI など）を使用するように設定します（n8n で対応する認証情報が設定されていることを確認してください）。
   • Memory： Simple Memory ノードに接続し、セッション内の会話履歴を保持します（セッション ID は Chat Trigger からリンクされます）。
   • System Prompt： AI の振る舞い、特に MCP を介してツールを特定して使用する方法を指示します。

     あなたは役に立つアシスタントです
     
     1. 利用可能なツールをすべて見つけます
     2. <user query> に基づいて、説明を参考に最適なツールを判断し、そのツール名をステップ 3 に渡します。また、ツールの実行時に渡すその他のパラメーターは、ツールのスキーマセクションを参照します。
     3. 正しいパラメーターを渡して executeTool を使用し、ツールを実行します
     

3. MCP Client Tool (List Tools)：
   • AI Agent の Tool 出力ハンドルに接続します。
   • MCP Brave Search (npx) 認証情報（ステップ 3 で作成）を使用します。
   • Operation： List Tools。これにより、AI Agent は「この認証情報で使用できるツールは何ですか？」と尋ねることができます。
4. MCP Client Tool (Execute Tool)：
   • こちらも AI Agent の Tool 出力ハンドルに接続します。
   • 同じ MCP Brave Search (npx) 認証情報を使用します。
   • Operation： Execute Tool。
   • Tool Name： {{ $fromAI('tool', 'selected tool to execute') }} のような式を使って動的に設定し、AI Agent が決定したツール名を取得します。
   • Tool Parameters： Defined automatically by the model に設定します。これにより、AI Agent はツールのスキーマ（List Tools のステップで取得したもの）とユーザーのリクエストに基づいて、必要なパラメーター（検索クエリなど）を判断できます。

使用方法／テスト

1. インポートした n8n ワークフローを有効化します。
2. n8n UI の Chat ボタンをクリックします（通常は右下にあります）。
3. ツール検出をテストする： What tools do you have? または list available tools と入力します。AI エージェントは「List Tools」MCP ノードを使用して、利用可能な Brave Search ツール（例：brave_web_search、brave_local_search）、その説明、想定されるパラメーターを返します。
4. ツール実行をテストする： Web 検索が必要な質問をします。例：Tell me about the latest developments in the Model Context Protocol.
5. 確認します：
   • チャット： AI エージェントが Brave Search ツールを使って取得した情報を返すことを確認します。
   • n8n 実行ログ： ワークフローの実行内容を確認します。AI エージェントノードが判断を行い、tool に brave_web_search が設定され、Tool_Parameters に検索クエリが含まれた状態で「Execute Tool」MCP クライアントノードが呼び出されているはずです。

トラブルシューティング／注意事項

• N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true： Docker コンテナーの起動時に、この環境変数が正しく設定されていることを確認してください。設定されていない場合、AI エージェントは MCP クライアントノードをツールとして使用できません。
• npx コマンド： 実行する MCP サーバーに応じて、npx コマンドと引数を再確認してください。パッケージ名（@modelcontextprotocol/server-brave-search）が正しいことを確認します。
• API キー： 必要な API キー（BRAVE_API_KEY など）が n8n の MCP クライアント認証情報の Environments セクションに正しく追加されており、キー自体も有効であることを確認してください。
• ファイアウォール： ローカルマシンのファイアウォールで、npx によるパッケージのダウンロードと実行が許可されていることを確認します。また、MCP サーバーから外部 API への接続が必要な場合は、その接続も許可されていることを確認してください。
• LLM 認証情報： AI エージェントノードで使用する Chat Model の認証情報（Groq、OpenAI など）が正しく設定され、有効であることを確認してください。
• Docker ボリューム： -v n8n_data:/home/node/.n8n ボリュームを使用すると、コンテナーを停止して再起動しても作業が保存されます。

まとめ

このワークフローでは、Model Context Protocol と npx 実行方式を使って n8n AI エージェントを柔軟かつ効率的に拡張する方法を示します。多くの一般的なユーティリティで永続的なサーバー設定を不要にすることで、外部ツールを統合するハードルを下げ、AI エージェントが外部の情報やサービスと動的にやり取りできるようにします。