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

使用本地 MCP 集成 n8n AI Agent（Docker + npx）

此代码库包含一个 n8n 工作流，演示如何将模型上下文协议（MCP）与本地运行的 n8n 实例（通过 Docker）集成，从而让 AI Agent 能够动态发现并使用外部工具（例如网页搜索），而无需持久安装服务。

此方法利用 n8n 凭据中的 npx 命令，即时运行 MCP 服务。

关键概念

• n8n AI Agent： n8n 中一个功能强大的节点，可借助大语言模型（LLM）和可用工具进行推理、规划并执行任务。
• 模型上下文协议（MCP）： 一种开放标准，旨在简化 AI 模型（例如 n8n AI Agent 使用的模型）与外部工具、数据源或 API 之间的通信。它就像一个通用翻译器。
• npx 方法： 无需永久安装即可运行 npm registry 中的 Node.js 包（例如 MCP 服务）。我们在 n8n 的命令行凭据中使用这种方法。
• Docker： 用于在本地隔离的容器环境中运行 n8n。

目标

此工作流的主要目标是展示如何：

1. 通过 Docker 在本地运行 n8n，并启用 AI Agent 工具使用所需的标志（N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE）。
2. 安装并使用社区节点 n8n-nodes-mcp。
3. 配置 n8n 凭据，以便使用 npx 动态运行 MCP 服务（例如 Brave Search）。
4. 构建一个 n8n AI Agent 工作流，使其能够：
   • 通过 MCP 发现可用工具（List Tools）。
   • 根据用户查询以及工具描述／架构智能地选择合适的工具。
   • 通过 MCP（Execute Tool）执行所选工具，并使用 AI 模型确定的参数。

前置条件

• 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_data 的 Docker 卷，以持久保存 n8n 工作流和数据。
• -e N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true：关键标志！ 此环境变量允许 AI Agent 节点将社区节点（例如 MCP Client）视为可执行工具。
• --rm：容器停止时自动将其删除。
• -it：以交互模式运行容器。

等待 n8n 启动。然后可以在浏览器中访问 http://localhost:5678。

步骤 2：安装 n8n MCP 社区节点

1. 在 n8n 界面（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： 配置为使用大模型（例如 Groq Chat Model、OpenAI 等——确保已在 n8n 中配置对应的凭据）。
   • Memory： 连接到 Simple Memory 节点，以在会话中保留对话历史记录（会话 ID 从 Chat Trigger 获取）。
   • System Prompt： 指示 AI 如何行动，特别是如何通过 MCP 识别和使用工具：

     You are a helpful assistant
     
     1. Find all the tools available
     2. From the <user query> work out which tool is best for the job based on the descriptions, and pass the name of that tool to the third step, and for other params to be passed when executing the tool take reference from the schema section of the tool.
     3. Use executeTool, passing in the correct parameters, for executing the tool
     

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 Agent 应与「List Tools」MCP 节点交互，并回复可用的 Brave Search 工具（例如，brave_web_search、brave_local_search）、工具说明及预期参数。
4. **测试工具执行：**提出需要网络搜索的问题，例如：Tell me about the latest developments in the Model Context Protocol.
5. 观察：
   • **聊天：**AI Agent 应使用 Brave Search 工具获取信息并作答。
   • **n8n 执行日志：**检查工作流执行情况。你应该能看到 AI Agent 节点做出决策，并且「Execute Tool」MCP Client 节点被调用，其 tool 设置为 brave_web_search，Tool_Parameters 中包含你的查询。

故障排除 / 备注

• **N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true：**启动 Docker 容器时，确保正确设置了此环境变量。否则，AI Agent 无法将 MCP Client 节点用作工具。
• **npx 命令：**仔细检查你尝试运行的特定 MCP 服务对应的 npx 命令及参数。确保软件包名称（@modelcontextprotocol/server-brave-search）正确。
• **API 密钥：**确认所有必需的 API 密钥（如 BRAVE_API_KEY）均已正确添加到 n8n 中 MCP Client 凭据的 Environments 部分，并且密钥本身有效。
• **防火墙：**确保本地计算机的防火墙允许 npx 下载并运行软件包；如果 MCP 服务需要访问外部 API，也要确保允许相关连接。
• **大模型凭据：**确保 AI Agent 节点使用的 Chat Model 凭据（例如，Groq、OpenAI）配置正确且有效。
• **Docker 卷：**使用 -v n8n_data:/home/node/.n8n 卷，即使停止并重启容器，也能确保保存你的工作。

总结

此工作流展示了一种灵活、高效的方式，可通过模型上下文协议和 npx 执行方法扩展 n8n AI Agent。它无需为许多常用工具设置持久化服务，降低了集成外部工具的门槛，让你的 AI Agent 能够动态地与外部信息和服务交互。