1. n8n-nodes-mcp 客户端节点完全指南

这是一份 n8n-nodes-mcp 社区节点的完整使用指南（翻译自官方 README）：从安装、凭证配置、环境变量，到支持的操作与 AI 代理工具集成，一站讲清。

• 节点介绍
• 快速上手
• 安装步骤
• 凭证配置
• 环境变量配置
• 支持的操作
• 作为 AI 代理的工具使用
• 兼容性要求
• 相关资源

1.1. 节点介绍

这是一个 n8n 社区节点，让您得以在 n8n 工作流中与模型上下文协议（MCP）服务器进行交互。

MCP 是一种协议，旨在让人工智能（AI）模型能够以标准化的方式与外部工具和数据源进行交互。该节点使您能够连接至 MCP 服务器、访问资源、执行工具并使用提示信息。

n8n 是一个基于 fair-code 许可协议 的工作流自动化平台。

1.2. 快速上手

官方快速入门视频：

1.2.1. 社区教学视频

特别感谢以下 n8n 社区视频的创作者，这些视频是学习使用此节点的宝贵资源：

• MCP 会是 N8N AI 代理的未来吗？（深度实测！）
• 通过 MCP 将 N8N AI 代理连接到万物？
• 构建一个能使用任何工具的 AI 代理（n8n 中的 MCP 实战教程）
• 全新的 N8N MCP 堪称颠覆性创新（Brave Search MCP 实践）
• MCP 与 n8n 自动化：MCP AI 代理终极指南（2025 版展望）
• REVOLUÇÃO na criação de AGENTES no N8N com o MCP Server!!! （葡萄牙语）

如果您制作了希望分享的优秀视频，欢迎告知，我会将其补充到列表中！

1.2.2. 想要深入了解 MCP？

欢迎观看我的 YouTube 系列视频 MCP 原理详解，获取更多关于模型上下文协议的信息。

1.3. 安装步骤

请参照 n8n 社区节点文档中的 安装指南 进行操作。

此外，请留意 将节点作为 AI 代理工具使用 时所需的环境变量设置。若需将 MCP 客户端节点用作 AI 代理的工具，则必须将环境变量 N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE 的值设为 true。

1.4. 凭证配置

MCP 客户端节点支持以下两种凭证类型，用于连接 MCP 服务器：

1.4.1. 基于命令行的传输方式（STDIO）

• 命令（Command）：用于启动 MCP 服务器的命令。
• 参数（Arguments）：传递给服务器命令的可选参数。
• 环境变量（Environment Variables）：以 NAME=VALUE 格式传递给服务器的变量。

1.4.2. 服务器发送事件（SSE）传输方式

• SSE URL：SSE 服务端点的 URL 地址（默认为 http://localhost:3001/sse）。
• 消息投递端点（Messages Post Endpoint）：用于发送消息的自定义端点地址（可选，若与 SSE URL 不同时指定）。
• 附加请求头（Additional Headers）：随请求一同发送的可选请求头（格式为 name:value，每行一个）。

1.5. 环境变量配置

当使用基于命令行的传输方式时，MCP 客户端节点支持通过以下两种途径向 MCP 服务器传递环境变量：

1.5.1. 方式一：通过凭证配置界面（UI）

您可以直接在凭证配置界面中添加环境变量：

这种方法适合个人配置和测试场景。环境变量的值将作为凭证信息安全地存储在 n8n 中。

1.5.2. 方式二：通过 Docker 环境变量

在 Docker 部署环境下，您可以通过为环境变量添加 MCP_ 前缀，直接将其传递给您的 MCP 服务器：

version: '3'

services:
  n8n:
    image: n8nio/n8n
    environment:
      - MCP_BRAVE_API_KEY=your-api-key-here
      - MCP_OPENAI_API_KEY=your-openai-key-here
      - MCP_CUSTOM_SETTING=some-value
    # 其他配置...

这些带有 MCP_ 前缀的环境变量将在您的 MCP 服务器启动执行时自动传递给它们。

1.5.3. 示例：使用 Brave Search MCP 服务器

本示例演示如何配置并使用 Brave Search MCP 服务器：

1. 安装 Brave Search MCP 服务器：

   npm install -g @modelcontextprotocol/server-brave-search
   

2. 配置 MCP 客户端凭证：

   • 命令：npx
   • 参数：-y @modelcontextprotocol/server-brave-search
   • 环境变量：添加一个变量 BRAVE_API_KEY=your-api-key（多个变量可用空格、逗号或换行符分隔）

3. 创建使用 MCP 客户端节点的工作流：

   • 添加一个 MCP 客户端节点。
   • 选择"列出工具 (List Tools)"操作，查看可用的搜索工具。
   • 再添加一个 MCP 客户端节点。
   • 选择"执行工具 (Execute Tool)"操作。
   • 从列表中选择 brave_search 工具。
   • 将参数设置为：{"query": "latest AI news"}。

该节点将执行搜索查询，并在其输出中返回结果。

1.5.4. 示例：结合 AI 代理的多服务器部署

本示例展示如何在生产环境中配置多个 MCP 服务器，并让 AI 代理调用它们：

1. 配置您的 docker-compose.yml 文件：

version: '3'

services:
  n8n:
    image: n8nio/n8n
    environment:
      # MCP 服务器所需的环境变量
      - MCP_BRAVE_API_KEY=your-brave-api-key
      - MCP_OPENAI_API_KEY=your-openai-key
      - MCP_SERPER_API_KEY=your-serper-key
      - MCP_WEATHER_API_KEY=your-weather-api-key
    
      # 允许社区节点作为 AI 代理的工具
      - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
    ports:
      - "5678:5678"
    volumes:
      - ~/.n8n:/home/node/.n8n

2. 在 n8n 中创建多个 MCP 客户端凭证实例：
   • Brave Search 凭证：
     • 命令：npx
     • 参数：-y @modelcontextprotocol/server-brave-search
   • OpenAI 工具凭证：
     • 命令：npx
     • 参数：-y @modelcontextprotocol/server-openai
   • 网页搜索凭证：
     • 命令：npx
     • 参数：-y @modelcontextprotocol/server-serper
   • 天气 API 凭证：
     • 命令：npx
     • 参数：-y @modelcontextprotocol/server-weather
3. 创建 AI 代理工作流：
   • 添加一个 AI 代理节点。
   • 启用 MCP 客户端作为其可用工具。
   • 配置多个 MCP 客户端节点实例，分别使用上述不同的凭证。
   • 设计一个需要调用多个数据源的提示（prompt）。

AI 代理提示示例：

请帮我规划一次旅行。首先，搜索 {destination_country} 的热门旅游目的地。
然后，查询排名前三的城市的当前天气状况。
最后，查找这些地方是否有最新的旅行限制相关新闻。

通过这种配置，AI 代理便能调用部署在不同服务器上的多个 MCP 工具，并且所有工具都依赖于您在 Docker 部署中统一配置的环境变量。

1.5.5. 示例：使用基于 SSE 的本地 MCP 服务器

本示例说明如何通过服务器发送事件（SSE）连接至在本地运行的 MCP 服务器：

1. 启动一个支持 SSE 的本地 MCP 服务器：

   npx @modelcontextprotocol/server-example-sse
   

   或者，您也可以运行自己开发的、支持 SSE 的自定义 MCP 服务器，并监听在 3001 端口。

2. 配置 MCP 客户端凭证：

   • 在节点设置中，选择 连接类型（Connection Type） 为 服务器发送事件（SSE）。
   • 创建一个新的凭证，类型选择 MCP 客户端（SSE）API。
   • 设置 SSE URL 为 http://localhost:3001/sse。
   • 如果您的服务器需要身份验证，请添加必要的请求头。

3. 创建使用 MCP 客户端节点的工作流：

   • 添加一个 MCP 客户端节点。
   • 将其连接类型设置为 服务器发送事件（SSE）。
   • 选择您刚创建的 SSE 凭证。
   • 选择"列出工具 (List Tools)"操作，查看服务器提供的可用工具。
   • 执行该工作流，观察返回的结果。

这种连接方式在以下场景中特别有用：

• 您的 MCP 服务器是作为一个独立服务运行的。
• 您需要连接到一个远程部署的 MCP 服务器。
• 您的服务器要求提供特殊的身份验证请求头。
• 您希望将数据传输通道与消息处理通道分离。

1.6. 支持的操作

MCP 客户端节点提供以下操作：

• 执行工具 (Execute Tool) - 调用指定的工具并传递参数。
• 获取提示 (Get Prompt) - 获取指定的提示模板。
• 列出提示 (List Prompts) - 获取所有可用的提示列表。
• 列出资源 (List Resources) - 获取 MCP 服务器提供的可用资源列表。
• 列出工具 (List Tools) - 获取所有可用的工具列表。
• 读取资源 (Read Resource) - 根据 URI 读取指定资源的内容。

1.6.1. 示例："列出工具"操作

"列出工具"操作会返回 MCP 服务器上所有可用的工具信息，包括工具名称、描述以及其所需的参数结构（schema）。

1.6.2. 示例："执行工具"操作

"执行工具"操作允许您选择并执行特定的工具，同时提供必要的参数。请务必从下拉菜单中选中您想要执行的工具。

1.7. 作为 AI 代理的工具使用

本节点可以作为 n8n AI 代理的一个工具来使用。若要启用社区节点作为工具，您需要将环境变量 N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE 的值设为 true。

1.7.1. 设置环境变量的方法

若您使用 bash 或 zsh 命令行界面：

export N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
n8n start

**若您使用 Docker 进行部署：**在您的 docker-compose.yml 文件中添加：

environment:
  - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

**若您使用的是 n8n 桌面应用程序：**在 n8n 的配置目录下创建一个名为 .env 的文件，并包含以下内容：

N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

**若您希望在 Mac 或 Linux 系统上永久生效：**将以下行添加到您的 ~/.zshrc 或 ~/.bash_profile 文件中：

export N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

AI 代理工作流执行结果示例：

在设置好此环境变量并重启 n8n 服务之后，您的 MCP 客户端节点即可在 AI 代理节点中作为可选工具进行调用。

1.8. 兼容性要求

• 要求 n8n 版本不低于 1.0.0。
• 兼容 MCP 协议版本 1.0.0 及以上。
• 支持通过 STDIO 和 SSE 两种传输方式连接 MCP 服务器。
• 使用 SSE 传输方式时，要求服务器端已实现 MCP 的服务器发送事件（Server-Sent Events）规范。

1.9. 相关资源

• n8n 社区节点官方文档
• 模型上下文协议 (MCP) 官方文档
• MCP TypeScript SDK （软件开发工具包）
• MCP 传输方式概览
• 在 MCP 中应用 SSE 的说明