企业官网建设流程全解析

如何配置 N8N_API_URL 和 N8N_API_KEY 启用 n8n-mcp 的工作流管理功能？

【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp

当你把 n8n-mcp 接入 Claude Desktop 等 MCP 客户端后，默认只能使用节点文档、搜索和校验这类只读工具。要让 AI 直接创建、更新、执行工作流，还需要在配置中提供N8N_API_URL和N8N_API_KEY两个环境变量，让 n8n-mcp 通过 n8n 实例的 API 操作工作流。本文以「本地已有一个可访问的 n8n 实例」为前提，说明如何取得 API 密钥、在 Claude Desktop 配置中写入这两个变量，并验证工作流管理工具是否生效。

配置前需要准备什么

根据 docs/SELF_HOSTING.md 和 .env.example 的说明：

• 一个可访问的 n8n 实例（本地 Docker、localhost:5678或远程实例均可）；
• 一个 n8n API 密钥：在 n8n 界面的Settings → API中创建（.env.n8n.example 标注的路径是Settings > n8n API > Create API Key）；
• n8n 实例的访问地址，注意N8N_API_URL要填不带/api/v1后缀的地址（.env.example 中明确写了 "n8n instance API URL (without /api/v1 suffix)"）；
• 按所选方式安装 n8n-mcp 所需的运行环境：npx 方式需要 Node.js，Docker 方式需要 Docker。

.env.example还定义了两个可选参数：N8N_API_TIMEOUT（API 请求超时，默认 30000 毫秒）和N8N_API_MAX_RETRIES（重试次数，默认 3）。一般保持默认即可，本文主路径不涉及它们。

在 Claude Desktop 配置中写入两个变量

npx 方式下，修改 Claude Desktop 的 MCP 配置文件（macOS 为~/Library/Application Support/Claude/claude_desktop_config.json，Windows 为%APPDATA%\Claude\claude_desktop_config.json，Linux 为~/.config/Claude/claude_desktop_config.json），在env中加入N8N_API_URL和N8N_API_KEY。以下是 docs/SELF_HOSTING.md 给出的完整配置（full configuration），其中https://your-n8n-instance.com和your-api-key需替换为你自己的实例地址和密钥：

{ "mcpServers": { "n8n-mcp": { "command": "npx", "args": ["n8n-mcp"], "env": { "MCP_MODE": "stdio", "LOG_LEVEL": "error", "DISABLE_CONSOLE_OUTPUT": "true", "N8N_API_URL": "https://your-n8n-instance.com", "N8N_API_KEY": "your-api-key" } } } }

几点文档中明确的条件：

• MCP_MODE: "stdio"是 Claude Desktop 场景必需的，否则会出现"Unexpected token..."之类的 JSON 解析错误，因为该变量保证 stdout 只输出 JSON-RPC 消息；
• 文档同时提供「Basic configuration」（不含这两个变量），只暴露文档和校验工具；加上这两个变量后，才会额外获得工作流管理能力（create、update、execute workflows）。也就是说，这两个变量就是文档工具与管理工具之间的开关；
• 两个变量必须同时提供。从 src/config/n8n-api.ts 的实现看，只配了 URL 没配 Key（或反之）时getN8nApiConfig()返回null，管理工具不会启用；
• 修改配置后必须重启 Claude Desktop。

如果你用 Docker 方式运行 n8n-mcp，同样是在启动参数里通过-e传入这两个变量，docs/SELF_HOSTING.md 给出的完整配置示例：

{ "mcpServers": { "n8n-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "--init", "-e", "MCP_MODE=stdio", "-e", "LOG_LEVEL=error", "-e", "DISABLE_CONSOLE_OUTPUT=true", "-e", "N8N_API_URL=https://your-n8n-instance.com", "-e", "N8N_API_KEY=your-api-key", "ghcr.io/czlonkowski/n8n-mcp:latest" ] } } }

Docker 方式下-i参数对 stdio 通信是必需的。

本地 n8n 实例的 URL 与 SSRF 门槛

这是最容易卡住的一步。如果你的 n8n 就跑在本机（例如 Docker 中的http://localhost:5678），文档要求：

• 容器里的 n8n-mcp 访问宿主机上的 n8n 时，N8N_API_URL应写成http://host.docker.internal:5678（docs/SELF_HOSTING.md 的 Tip）；
• 同时必须加WEBHOOK_SECURITY_MODE=moderate。文档说明：同一套 SSRF 门槛同时覆盖 webhook 触发和 n8n API 客户端（即N8N_API_URL），默认的strict模式会拒绝 loopback 地址；moderate允许 localhost，同时仍会拦截 RFC1918 私网地址和云元数据接口。.env.example 中对该变量的说明与此一致（moderate 的典型场景即http://localhost:5678或http://host.docker.internal:5678的本地 n8n）。

{ "mcpServers": { "n8n-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "--init", "-e", "MCP_MODE=stdio", "-e", "LOG_LEVEL=error", "-e", "DISABLE_CONSOLE_OUTPUT=true", "-e", "N8N_API_URL=http://host.docker.internal:5678", "-e", "N8N_API_KEY=your-api-key", "-e", "WEBHOOK_SECURITY_MODE=moderate", "ghcr.io/czlonkowski/n8n-mcp:latest" ] } } }

替代路径：用 .env 文件配置

docs/SELF_HOSTING.md 在本地安装（开发）方式下说明：n8n API 凭据可以写在.env文件（从.env.example复制）中，也可以直接写在客户端配置里。在.env中对应的位置是：

# n8n instance API URL (without /api/v1 suffix) # Example: https://your-n8n-instance.com N8N_API_URL= # n8n API Key (get from Settings > API in your n8n instance) N8N_API_KEY=

两条路径二选一即可，不要混用造成两处值不一致。

验证工作流管理功能已启用

1. 用 n8n_health_check 工具确认连接

README.md 列出的管理工具中，n8n_health_check属于 System Tools，用于「Check n8n API connectivity and features」。它的工具文档（src/mcp/tool-docs/system/n8n-health-check.ts）明确列出的前提正是「Requires N8N_API_URL and N8N_API_KEY to be configured」，并建议「Use before starting workflow operations to ensure n8n is responsive」。

在 AI 客户端中调用该工具，返回对象包含status（整体健康状态，取值为'healthy'、'degraded'、'error'）、n8nVersion、features（可用功能及状态）和nextSteps（建议的下一步）等字段。status不是healthy，或features中功能状态异常，说明N8N_API_URL/N8N_API_KEY尚未正确生效——这比猜测工具列表是否出现更直接。

2. 确认管理工具可用

配置生效的标志是 README.md 中「n8n Management Tools (16 tools - Requires API Configuration)」这一组工具出现在客户端的工具列表里，例如n8n_create_workflow、n8n_list_workflows、n8n_get_workflow、n8n_validate_workflow、n8n_executions等。反过来，如果客户端里只有文档与校验类工具，通常意味着两个变量没有同时写入或客户端没有重启。

3. 用 curl 单独验证 n8n 侧的凭据

如果健康检查报连接问题，先排除 n8n 实例本身的问题。docs/N8N_DEPLOYMENT.md 给出的验证方式是直接请求 n8n API（URL 换成你的实例，Key 换成你的密钥）：

curl -H "X-N8N-API-KEY: your-api-key" \ https://your-n8n-instance.com/api/v1/workflows

该命令能返回工作流列表，说明实例地址和 API 密钥本身可用，问题应出在 n8n-mcp 侧的配置（URL 后缀、SSRF 模式等）；命令失败则先按 n8n 侧排查。

连接失败时对照文档排查

docs/N8N_DEPLOYMENT.md 的 Troubleshooting 一节列出的 "Cannot connect to n8n API" 常见原因，与这两个变量直接相关：

另有一条与部署方式相关的提示：docs/N8N_DEPLOYMENT.md 的环境变量参考表中，N8N_API_URL/N8N_API_KEY标注为「Required only for workflow management features. Documentation tools work without these」，与 docs/SELF_HOSTING.md 中「凭据可选，缺省时只有文档与校验工具」的表述一致——如果你发现配置后行为停留在文档工具层面，先确认这两个变量确实写入了实际运行的那一份配置。

适用范围说明

本文的主路径是 MCP 客户端（Claude Desktop 等）以 stdio 方式运行 n8n-mcp。如果你要走的是 n8n 反向连接 n8n-mcp 的 HTTP 模式（n8n 的 MCP Client Tool 节点连到 n8n-mcp），环境变量组合不同（N8N_MODE=true+MCP_MODE=http，且需要MCP_AUTH_TOKEN/AUTH_TOKEN），验证方式也改为curl http://localhost:3000/health和/mcp端点，详见 docs/N8N_DEPLOYMENT.md；其中N8N_API_URL/N8N_API_KEY的取值要求与本文相同。

【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp