n8n 中文文档

连接到 n8n MCP 服务器

n8n 的内置 MCP 服务器允许受支持的客户端(例如 Lovable 或 Claude Desktop)安全连接到您的 n8n 实例。连接后,这些客户端可以:

  • 搜索您的工作流程
  • 与 MCP 中标记为可用的工作流程进行交互
  • 触发并测试公开的工作流程
  • 创建和编辑工作流程和数据表

本节内容

提示

要连接 Claude Desktop 等聊天客户端吗?

  1. 在您的实例上启用 MCP 访问。
  2. 从 Settings 设置 > Instance-level MCP 实例级 MCP > Connect a client 连接客户端 中复制 Server URL 服务器 URL。该 URL 以 /mcp-server/http 结尾。
  3. 将其粘贴到客户端中。有关各客户端的具体步骤,请参阅 MCP 客户端连接示例。

本页其余内容介绍这些步骤涉及的设置、权限和故障排除信息。

实例级 MCP 访问与 MCP Server Trigger 节点的区别

实例级 MCP 访问允许您为每个 n8n 实例创建一个连接、使用集中式身份验证并选择启用哪些工作流程进行访问。启用的工作流程很容易找到并运行,无需为每个工作流程进行额外的设置。

相比之下,您可以在单个工作流程中配置 MCP 服务器触发器节点。此节点仅公开来自该工作流程的工具,当您想要在一个工作流程中制作特定的 MCP 服务器行为时,这是一种有用的方法。

使用实例级 MCP 访问时的关键注意事项

  • MCP 支持两种类型的工作流交互:使用工作流执行工具运行现有工作流,以及构建或编辑工作流(从 n8n 2.13.0 开始提供)。
  • 它不提供对实例中所有工作流程的全面了解。您必须在实例级别启用 MCP,然后单独启用每个工作流。唯一的例外是 search_workflows,它可以访问当前用户有权查看的每个工作流程,但仅返回预览,而不返回完整的工作流程数据。
  • 它的范围不限于每个 MCP 客户端。您连接的所有客户端(例如,Claude Desktop 和 ChatGPT)都可以查看您为 MCP 访问启用的所有工作流程。您无法将特定工作流程限制到特定客户端。在用户级别,可见性仍然是用户范围的:用户只能看到他们有权访问的启用 MCP 的工作流程。
  • 大多数 MCP 工具适用于未发布的工作流程。 execute_workflow 是例外,它默认为生产模式并运行工作流的已发布版本。它还支持 manual 执行模式来运行当前(未发布)版本。

启用MCP访问

提示

功能可用性

n8n 2.33.0 中提供了下述设置布局(连接详细信息、访问、连接的客户端)、连接客户端 对话框和 允许的回调 URL。这些取代了以前的单页 MCP 设置屏幕。在旧版本上,此页面显示更简单的布局,无需每个客户端设置步骤。

对于云和自托管实例

  1. 导航到 设置 > 实例级 MCP。
  2. 选择启用 MCP 访问(需要实例所有者或管理员权限)。

启用 MCP 访问前的实例级 MCP 页面,显示启用 MCP 访问按钮

启用后,该页面将设置分为三个部分:

  • 连接详细信息:显示 MCP 状态 和一个 连接 按钮,用于打开 MCP 客户端的设置步骤。
  • 访问:显示向 MCP 客户端公开的工作流程(以及代理,如果您的实例具有代理功能,则为代理),请参阅 向 MCP 客户端公开工作流程 和 将代理暴露给 MCP 客户端。实例所有者和管理员还可以在此处查看允许的回调 URL,请参阅 限制 OAuth 回调 URL。
  • 连接的客户端:预览最多三个你自己的已连接客户端及其权限,并显示当前有多少客户端可以访问。选择客户端可打开其详细信息,或者选择 Revoke access 撤销访问权限 将其断开。选择 View all 查看全部 可查看或撤销各个客户端的访问权限。

启用 MCP 访问后的实例级 MCP 页面,显示连接详细信息、访问和已连接的客户端

要禁用: 在 连接详细信息 中,选择 MCP 状态 控件,然后选择 禁用。 n8n 要求您确认,因为禁用会断开每个连接的客户端并撤销其访问权限。您可以稍后重新打开 MCP 访问权限。

提示

环境变量(仅限自托管)

在自托管实例上,您还可以使用环境变量管理 MCP 设置。参见 使用环境变量管理实例设置。

对于自托管:完全禁用

要完全删除该功能,请设置环境变量:

N8N_DISABLED_MODULES=mcp

此操作将删除 MCP 端点并隐藏所有相关的 UI 元素。

连接 MCP 客户端

提示

功能可用性

n8n 2.33.0 中提供了每个客户端连接设置步骤。早期版本不显示这些步骤。请使用 MCP客户端连接示例 中的手动说明来配置您的客户端。

在 连接详细信息 中,选择 连接 以打开 连接客户端 对话框,然后选择身份验证方法:OAuth(推荐) 或 API 密钥。

使用OAuth(推荐)

  1. 导航到 设置 > 实例级 MCP。
  2. 在“连接详细信息”中,选择“连接”以打开“连接客户端”对话框。
  3. 确认当前位于 OAuth(推荐) 选项卡。
  4. 在 Your client 客户端 下拉列表中,选择您的 AI 助手、IDE 或 CLI。n8n 将客户端分为 CLI(Claude Code、Codex、Gemini CLI)、Web(Claude.ai、ChatGPT、Mistral Vibe)和 IDE(Cursor、VS Code、Windsurf),并显示根据您的选择量身定制的设置步骤。
  5. 请按照针对您的客户端类型显示的步骤进行操作: * Web 客户端:选择 One-click setup 一键设置,将 n8n 直接添加到客户端;或者复制 Server URL 服务器 URL,手动粘贴到客户端自己的连接器设置中。 * CLI 客户端:运行所示的安装命令,或将手动配置片段添加到客户端的配置文件中。无论哪种方式,请完成 Authenticate 身份验证 步骤以完成 OAuth 登录(有关确切命令,请参阅 Claude Code 和 Codex 示例)。 * IDE 客户端:选择一键安装链接(编辑器支持的情况下),或复制 Server URL 服务器 URL 并自行将手动配置片段添加到编辑器中。
  6. 当客户端将您重定向到 n8n 时,批准访问以完成连接。

审查并撤销客户端访问权限

每个连接的客户端仅具有您在连接时授予的权限,例如读取工作流程,而无法创建或运行它们。要审查或撤销客户端的访问权限:

  1. 导航到 设置 > 实例级 MCP。
  2. 在已连接的客户端中,选择预览的客户端以打开其详细信息,或选择 Revoke access 撤销访问权限 将其断开。对于未预览的客户端,请选择 View all 查看全部。切换到所有用户视图可查看其他用户的客户端。此处会显示已连接 OAuth 客户端、其访问级别以及连接时间的表。使用 API Key 的客户端不会出现在此处,因为它们使用 bearer token 而不是 OAuth 连接进行身份验证。
  3. 选择客户的行以打开其详细信息并查看您授予它的每个权限,或者直接在该行上选择“撤消访问权限”以直接跳至撤消。
  4. 确认撤销。 n8n 立即断开客户端连接;它必须重新连接并再次登录才能重新获得访问权限。

使用 API 密钥

  1. 导航到 设置 > 实例级 MCP。
  2. 在“连接详细信息”中,选择“连接”以打开“连接客户端”对话框。
  3. 切换到 API key API 密钥 选项卡。当您第一次打开它时,n8n 会自动生成与您的用户帐户绑定的个人访问令牌。
  4. 复制您需要的内容:配置 JSON 块,已填充您的服务器 URL 和携带令牌的 Authorization: Bearer 标头,或者单个 服务器 URL 和访问令牌值(如果您的客户端不使用该 JSON 格式,例如 Codex 的 TOML 配置)。离开此选项卡后,n8n 仅显示经过编辑的令牌值,除非您轮换令牌,否则您将无法再次复制它。
  5. 将您复制的内容粘贴到 MCP 客户端的配置中:对于接受 mcpServers JSON 代码段的客户端,直接将 配置 JSON 放入其中,或者为需要不同格式的客户端使用单独的 服务器 URL 和令牌。此选项卡不是特定于客户端的,因此无论您设置哪个客户端,相同的值都适用(有关特定于客户端的格式,请参阅 MCP客户端连接示例)。

轮换您的访问令牌

如果您丢失了令牌或需要轮换它:

  1. 导航到 设置 > 实例级 MCP。
  2. 在“连接详细信息”中,选择“连接”以打开“连接客户端”对话框。
  3. 切换到 API key 选项卡。
  4. 使用编辑值旁边的按钮生成新令牌。

    当您生成新令牌时,n8n 会撤销之前的令牌。 5. 使用新值更新所有连接的 MCP 客户端。

将工作流程公开给 MCP 客户端

MCP 客户端可以使用 search_workflows 发现当前用户有权访问的所有工作流程预览。客户端无法访问完整的工作流数据、执行或修改工作流,除非您显式启用该工作流的 MCP 访问权限。

启用对各个工作流程的访问

选项 1:从 Workflows enabled 已启用的工作流页面

从 Workflows enabled 已启用的工作流 页面(从 n8n 2.2.0 开始提供;在 n8n 2.42.0 中由 Workflows exposed 公开的工作流 更名),你可以启用对各个工作流的访问: 1. 导航到 设置 > 实例级 MCP。 2. 选择 Workflows enabled 已启用的工作流。 3. 单击 启用工作流程 按钮(在工作流程表标题中或在表的空状态下)。 4. 搜索所需的工作流程(按名称或描述)并从列表中选择它。 5. 单击启用进行确认。

选项 2:从工作流程编辑器

  1. 打开工作流程。
  2. 单击右上角的主 Workflow menu 工作流菜单 (...)。
  3. 选择设置。
  4. 切换 在 MCP 中可用。

选项 3:从工作流程列表

  1. 转到工作流程。
  2. 打开工作流程卡上的菜单。
  3. 选择启用 MCP 访问。

启用项目/文件夹 的访问

提示

功能可用性

从 n8n 2.24.0 开始,可提供项目和文件夹级 MCP 访问控制。

您可以使用工作流列表中的选项菜单 Options menu 来切换当前项目或文件夹中所有工作流的 MCP 访问权限:

  1. 导航到所需的项目并从顶部菜单中选择“工作流程”,然后根据需要打开子文件夹。
  2. 选择项目或文件夹名称旁边的 选项 菜单 Options icon。
  3. 选择管理 MCP 访问,然后启用 MCP 或 禁用 MCP。

Options 菜单展开 Manage MCP access,显示 Enable MCP access 和 Disable MCP access

提示

注意

这将为当前位于选定项目或文件夹中的所有工作流切换 MCP 访问权限(跳过已处于所选状态的工作流)。如果希望以后创建的工作流无需逐个切换即可公开,请使用自动公开新工作流。

自动公开新工作流

提示

功能可用性

从 n8n 2.36.0 开始,自动公开新工作流功能会逐步推出。此设置可能尚未出现在所有实例上。

你可以自动公开每个新建工作流,无需逐个启用 MCP 访问权限:

  1. 导航到 Settings 设置 > Instance-level MCP 实例级 MCP。
  2. 开启 Auto-expose new workflows 自动公开新工作流。

此设置默认关闭。开启后仅影响之后创建的工作流。已有工作流会保留当前设置,因此请使用为单个工作流启用访问权限或为项目/文件夹启用访问权限来公开这些工作流。

只有实例 Owner 和 Admin 可以更改此设置。在通过环境变量管理 MCP 访问权限的实例上,此设置为只读。

提示

注意

如果实例禁用了 MCP 访问权限,开启此设置不会公开任何内容。

管理访问

Workflows enabled 已启用的工作流页面(Access 访问 > Workflows enabled 已启用的工作流)列出 MCP 客户端可以访问和操作的每个工作流。你可以从此列表:

  • 直接打开工作流程、其主项目或父文件夹
  • 使用操作菜单撤销访问权限(或使用工作流程卡菜单中的 禁用 MCP 访问权限)
  • 使用操作菜单更新工作流程描述(或使用工作流程编辑器中的菜单)
  • 使用 启用工作流程 按钮启用对更多工作流程的访问(可从 n8n 2.2.0 开始使用)

工作流程描述

为了帮助 MCP 客户端识别工作流程,您可以添加自由文本描述,如下所示:

  1. 选项 1:从 Workflows enabled 已启用的工作流 页面
  2. 导航到 设置 > 实例级 MCP。
  3. 选择 Workflows enabled 已启用的工作流。
  4. 使用所需工作流程行中的操作菜单,然后选择 编辑描述 操作。
  5. 或者,直接单击描述文本以打开编辑对话框。
  6. 选项 2:从工作流程编辑器

    1. 打开工作流程。
    2. 单击右上角的主 Workflow menu 工作流菜单 (...)。
    3. 选择编辑描述。

    工作流主菜单已打开,其中 Edit description 处于突出显示状态

将代理暴露给 MCP 客户端

提示

功能可用性

Agents 是一项独立于工作流的功能。详细信息请参阅构建和管理 agents。MCP 客户端从 n8n 2.34.0 开始可以管理 agents。在 n8n Cloud 上,运行最新稳定版本的账户默认启用 agents。在自托管环境中,仅当启用了 agents 模块时,此部分才适用。

提示

预览状态

代理处于预览版,可能会在未来版本中发生变化。避免在生产工作流程中依赖它们。

如果您的实例具有代理功能,访问部分还会显示暴露的代理。与工作流程一样,MCP 客户端无法读取或管理代理,除非您显式启用 MCP 访问权限。

启用单个代理的访问权限

选项 1:从 MCP 设置页面

  1. 导航到 设置 > 实例级 MCP。
  2. 选择 Agents exposed 已公开的代理。
  3. 选择启用代理。
  4. 按名称搜索所需的代理并从列表中选择它。
  5. 选择启用进行确认。

选项 2:来自代理构建器

  1. 在代理生成器中打开代理。
  2. 打开其 MCP 设置。
  3. 切换 在 MCP 中可用。

管理代理访问

暴露的代理页面显示了为 MCP 客户端启用的每个代理及其名称及其项目或文件夹位置。从这个列表中您可以:

  • 直接打开代理或其项目。
  • 从其行中删除单个代理的访问权限,或选择多个代理并一次删除所有访问权限。
  • 使用 启用代理 按钮启用更多代理的访问权限。

限制 OAuth 回调 URL

实例所有者和管理员可以限制 OAuth 客户端登录后可以重定向到的 URL。默认情况下,n8n 允许任何回调 URL,但安全性较低。

  1. 导航到 设置 > 实例级 MCP。
  2. 在 访问 中,选择 允许的回调 URL。
  3. 选择一种模式: * 所有回调 URL:任何 URL 都可以完成 OAuth 登录。 * 仅受信任的 URL:只有您列出的 URL 才能完成 OAuth 登录。
  4. 如果您选择 仅受信任的 URL,请添加您信任的每个 URL,然后选择 保存。

工具和资源

提示

考虑使用编码代理(例如 Claude 代码或 Google ADK 代理)而不是聊天客户端作为 MCP 客户端。编码代理专门用于生成和验证 TypeScript 代码,非常适合以编程方式构建工作流程。

n8n MCP 服务器公开了用于工作流管理、工作流构建、代理管理、用户偏好和数据表的工具。有关可用工具及其参数的完整列表,请参阅 MCP 服务器工具参考。

面向编码代理的 n8n Skills

当您将编码代理连接到 n8n MCP 服务器时,代理可以构建和编辑工作流,但它不会自动了解 n8n 的表达式、节点配置、错误处理和其他模式的约定。n8n Skills 为代理提供相关知识,以便其一次性获得正确的工作流。

n8n Skills 是在 n8n-io/skills 存储库中发布的一组能力模块。它们与实例级 MCP 服务器配对,包括:

  • 13 项能力 Skills 涵盖工作流最佳实践,包括子工作流、表达式、循环、AI 代理、错误处理、凭证、数据表和调试。
  • 50 多个参考文档和示例,包含每个节点的指导、决策树和可复制粘贴的工作流片段。
  • 挂钩自动加载正确的指导,因此代理在进行高影响力的 MCP 调用之前会读取相关技能。

第 14 个元技能 using-n8n-skills-official 将代理路由到每个任务的匹配能力技能。

为什么使用 Skills

技能在代理需要时加载指导,而不是依赖于模型的一般知识。这有助于代理:

  • 遵循适用于其所使用的节点或功能的 n8n 最佳实践。
  • 避免常见错误,例如不正确的表达式语法或缺少错误处理。
  • 生成需要更少来回修复的工作流程。

这些技能是简单的 Markdown,因此您可以根据自己的约定阅读、fork 和修改它们。

安装 Skills

n8n-io/skills 存储库具有 Claude Code、Codex 和其他编码代理的最新安装说明。按照存储库 README 中的步骤将 Skills 添加到您的代理。

示例

用于连接特定客户端的精确命令和配置,包括 Lovable、Claude Desktop、Claude Code、Codex、Gemini CLI、Cursor、VS Code、Windsurf 和 Google ADK 代理,请参阅 MCP 客户端连接示例。

故障排除

如果您在将 MCP 客户端连接到 n8n 实例时遇到问题,请考虑以下事项:

  • 如果您使用基于云的 MCP 客户端,请确保您的 n8n 实例可公开访问。
  • 验证是否在 n8n 设置中启用了 MCP 访问。
  • 检查您要执行或修改的工作流程是否标记为“在 MCP 中可用”。
  • 确认 MCP 客户端中的身份验证方法(OAuth 或 API 密钥)配置正确。
  • 如果实例运行在反向代理、负载均衡器或 Web 应用防火墙(WAF)后,请确保它不会移除 MCP 请求标头。请参阅 MCP 请求标头。
  • 查看 n8n 服务器日志中是否有与 MCP 连接相关的任何错误消息。

授权客户端时权限不足

客户端将您转到 n8n 以批准访问,但您进入的页面显示 You do not have sufficient permissions to authorize this request。

对于实例级 MCP 服务器,这表示您的实例尚未启用 MCP 访问。虽然该消息没有明确说明,但没有其他原因:MCP 服务器启用时,任何已登录用户都可以批准客户端;MCP 服务器停用时,n8n 会拒绝所有用户。

请实例所有者或管理员将其启用(请参阅启用 MCP 访问),然后重新连接客户端。

MCP 请求标头

提示

功能可用性

从 n8n 2.36.0 开始,n8n 的 CORS 策略允许这些路由标头。

MCP 客户端会向 n8n MCP 端点发送以下标头:

  • MCP-Protocol-Version
  • Mcp-Method
  • Mcp-Name

如果将 n8n 部署在会移除未知标头或仅转发允许列表中标头的反向代理、负载均衡器或 Web 应用防火墙(WAF)后,请将这三个标头加入允许列表。否则客户端可能无法连接,或回退到较旧的协议版本。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。