n8n AI Agent 与本地 MCP 集成 (Docker + npx)

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

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

关键概念

• n8n AI Agent: n8n 中一个强大的节点，可以使用大型语言模型 (LLM) 和可用工具进行推理、计划和执行任务。
• 模型上下文协议 (MCP): 一种开放标准，旨在简化 AI 模型（如 n8n AI Agent 使用的模型）与外部工具、数据源或 API 之间的通信。它就像一个通用翻译器。
• npx 方法: 允许从 npm 注册表运行 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 UI（位于 http://localhost:5678）中，导航到 Settings > Community Nodes。
2. 单击 Install。
3. 在搜索框中输入 n8n-nodes-mcp。
4. 阅读并同意与社区节点相关的风险。
5. 单击 Install。

步骤 3：配置 MCP Client 凭据（使用 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 识别和使用工具：

     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
     

     (翻译) 你是一个乐于助人的助手

     1. 找到所有可用的工具
     2. 从 <用户查询> 中，根据描述确定哪个工具最适合该任务，并将该工具的名称传递给第三步，并且对于执行该工具时要传递的其他参数，请参考该工具的 schema 部分。
     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 根据工具的 schema（它从 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. 观察:
   • Chat: AI Agent 应使用 Brave Search 工具收集的信息进行响应。
   • n8n Executions Log: 检查工作流执行情况。您应该看到 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）。
• LLM 凭据: 确保 AI Agent 节点中使用的 Chat Model 凭据（例如，Groq、OpenAI）已正确配置且有效。
• Docker Volume: 使用 -v n8n_data:/home/node/.n8n 卷可确保即使您停止并重新启动容器，您的工作也会被保存。

结论

此工作流演示了一种灵活有效的方法，可以使用模型上下文协议和 npx 执行方法来扩展 n8n AI Agent。它通过避免为许多常用实用程序设置持久服务器的需求来降低集成外部工具的门槛，从而允许您的 AI Agent 动态地与外部信息和服务进行交互。