如何配置 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 Keyn8n 实例的访问地址注意N8N_API_URL要填不带/api/v1后缀的地址.env.example 中明确写了 n8n instance API URL (without /api/v1 suffix)按所选方式安装 n8n-mcp 所需的运行环境npx 方式需要 Node.jsDocker 方式需要 Docker。.env.example还定义了两个可选参数N8N_API_TIMEOUTAPI 请求超时默认 30000 毫秒和N8N_API_MAX_RETRIES重试次数默认 3。一般保持默认即可本文主路径不涉及它们。在 Claude Desktop 配置中写入两个变量npx 方式下修改 Claude Desktop 的 MCP 配置文件macOS 为~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 为%APPDATA%\Claude\claude_desktop_config.jsonLinux 为~/.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_MODEstdio, -e, LOG_LEVELerror, -e, DISABLE_CONSOLE_OUTPUTtrue, -e, N8N_API_URLhttps://your-n8n-instance.com, -e, N8N_API_KEYyour-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:5678docs/SELF_HOSTING.md 的 Tip同时必须加WEBHOOK_SECURITY_MODEmoderate。文档说明同一套 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_MODEstdio, -e, LOG_LEVELerror, -e, DISABLE_CONSOLE_OUTPUTtrue, -e, N8N_API_URLhttp://host.docker.internal:5678, -e, N8N_API_KEYyour-api-key, -e, WEBHOOK_SECURITY_MODEmoderate, 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 APIURL 换成你的实例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 常见原因与这两个变量直接相关现象/原因对应处理N8N_API_URL缺少协议前缀URL 必须带http://或https://API 密钥过期或无效到 n8n Settings → API 重新创建并更新配置n8n 实例从 n8n-mcp 所在主机不可达检查网络本机容器场景改用host.docker.internal:5678并加WEBHOOK_SECURITY_MODEmoderaten8n 的 API 功能被禁用在 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_MODEtrueMCP_MODEhttp且需要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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考