在 Codex CLI 中接入 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 接入 OpenAI Codex CLI让 Codex 在命令行环境中获得 n8n 节点文档、属性与操作的结构化访问能力从而辅助开发者设计、构建并校验 n8n 工作流。通过阅读本文你将掌握 Codex 的config.tomlMCP 配置写法、文档工具与 n8n 管理工具两种配置档位的差异、/mcp命令的服务器状态管理方法以及通过AGENTS.md项目指令提升 Codex 生成工作流质量的最佳实践。配置完成后Codex 即可像 Claude Code、Cursor、Windsurf 一样直接调用 n8n-MCP 提供的数十个 MCP 工具涵盖节点搜索、模板检索、工作流校验与 n8n 实例管理。前置条件已安装并能够启动 Codex CLI系统可访问 npm 仓库n8n-MCP 通过npx n8n-mcp按需拉起若需要使用工作流管理类工具n8n_*前缀请先准备好一个可用的 n8n 实例地址与 API Key在 n8n 的Settings → API中生成。n8n-MCP 是一款基于 Model Context Protocol 的 MCP 服务器其文档与校验类工具在离线状态下基于仓库内置的 SQLite 节点数据库运行以n8n_前缀开头的管理类工具则作用于运行中的 n8n 实例必须配置 API 才能使用。这一点在后续配置中会直接体现为基础配置与完整配置两档。更新 Codex 配置文件Codex 的 MCP 服务器配置统一维护在用户目录下的~/.codex/config.toml文件中。找到该文件后在末尾追加一个[mcp_servers.n8n]配置块即可。基础配置仅文档工具如果你只需要让 Codex 查询 n8n 节点文档、属性与模板信息不涉及对 n8n 实例的写入操作可以使用以下最小配置[mcp_servers.n8n] command npx args [n8n-mcp] env { MCP_MODE stdio, LOG_LEVEL error, DISABLE_CONSOLE_OUTPUT true }完整配置含 n8n 管理工具若希望 Codex 具备完整的工作流管理能力创建、更新、校验、删除工作流管理执行记录等需要额外提供 n8n 实例的 API 地址与密钥[mcp_servers.n8n] 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 }请务必将https://your-n8n-instance.com替换为你的实际 n8n 访问地址将your-api-key替换为真实的 n8n API Key。若 n8n 运行在本机可使用http://localhost:5678。配置参数解析上述三组环境变量的作用分别如下它们直接决定了 MCP 服务器的运行方式环境变量取值作用MCP_MODEstdio声明以标准输入/输出stdio传输模式运行这是 Codex 等本地 MCP 客户端与服务器进程通信的标准方式LOG_LEVELerror将日志级别压缩到仅输出错误避免信息日志干扰命令行体验DISABLE_CONSOLE_OUTPUTtrue禁止服务器向控制台输出非协议内容保证 stdout 通道只承载 JSON-RPC 消息N8N_API_URLn8n 实例地址n8n 管理工具的 API 基地址可选缺省时管理工具不可用N8N_API_KEYn8n API Keyn8n API 鉴权密钥可选与N8N_API_URL需成对出现从源码层面看这组配置并不是表面功夫在 stdio-wrapper.ts 中服务器进程启动前就会强制执行process.env.MCP_MODE stdio、DISABLE_CONSOLE_OUTPUT true、LOG_LEVEL error并安装 stdio 守护installStdioGuard屏蔽一切非 JSON-RPC 输出防止污染 stdout 协议通道logger.ts 则在MCP_MODE stdio或DISABLE_CONSOLE_OUTPUT true时抑制全部控制台日志只有开启调试开关时才会放行错误日志。而N8N_API_URL/N8N_API_KEY是否配置则由 n8n-api.ts 中的 zod 校验统一把关两者必须同时存在才返回有效配置任一缺失都会被判定为未配置 n8n API进而隐藏全部管理类工具——这正是基础配置只提供文档工具这一行为的实现来源。该文件还揭示了另外两个可选的调优项N8N_API_TIMEOUT默认 30000ms与N8N_API_MAX_RETRIES默认 3 次以及 Cloudflare Access 场景下的N8N_CF_CLIENT_ID/N8N_CF_CLIENT_SECRET有需要时可在env中一并追加。管理 MCP 服务器完成配置后进入 Codex CLI使用斜杠命令/mcp即可查看 MCP 服务器的连接状态与可用工具列表。从仓库实际收录的截图可以看到连接成功后 Codex 中会显示名为n8n的服务器启动命令为npx n8n-mcp并列出可供调用的全部工具涵盖节点与模板查询search_nodes、get_node_info、list_nodes、search_templates、get_template、list_templates等工作流校验validate_workflow、validate_workflow_connections、validate_workflow_expressions、validate_node_minimal等n8n 实例管理n8n_create_workflow、n8n_update_partial_workflow、n8n_validate_workflow、n8n_list_workflows、n8n_get_execution、n8n_health_check等。需要说明的是具体可用工具数量取决于配置档位仅配置文档工具时管理类n8n_*工具不会出现。排查连接问题时可依次确认~/.codex/config.toml语法是否正确尤其注意env内联表的引号、npx n8n-mcp能否在终端正常拉起、以及N8N_API_URL/N8N_API_KEY是否成对且可达。为 Codex 配置项目指令为了让 Codex 在构建 n8n 工作流时遵循最佳实践官方推荐在项目根目录创建AGENTS.md文件并将主 README 的Claude Project Setup一节README.md中的系统指令复制进去。AGENTS.md是 Codex 的项目指令约定文件其中的内容会被注入到 Codex 的上下文用于约束其行为方式。针对 n8n 工作流开发核心要点包括静默执行Silent Execution调用工具期间不输出评论全部工具执行完毕后再统一回复并行执行Parallel Execution相互独立的查询如节点搜索与模板搜索应并行发起模板优先Templates First动手搭建前先通过search_templates检索现成模板多级校验Multi-Level Validation遵循validate_node(modeminimal)→validate_node(modefull)→validate_workflow的校验链路绝不信任默认值Never Trust Defaults所有控制节点行为的参数必须显式配置默认参数值是运行时故障的首要来源。此外指令中还包含完整的 8 步工作流构建流程模板发现 → 节点发现 → 配置 → 校验 → 构建 → 工作流校验 → 部署、四级校验策略、批量更新操作n8n_update_partial_workflow的addConnection四参数写法与 IF 节点的branch分支路由等细则。将这些规则写入AGENTS.md后Codex 在命令行中构建 n8n 工作流时将显著减少参数缺省、连接错误等常见问题。仓库根目录已有一份 AGENTS.md 实例可供参考其中除项目概览外还记录了模块组织、MCP 约定如校验 profile 为minimal/runtime/ai-friendly/strict、优先使用 diff 式工作流更新等与安全配置规范可作为自建AGENTS.md的模板。安全使用提醒无论使用哪一档配置都请注意以下安全边界不要直接在生产工作流上执行 AI 修改使用前先复制工作流、在开发环境测试、导出重要工作流的备份并将变更校验通过后再部署管理工具是写通道配置了N8N_API_URL/N8N_API_KEY后Codex 便具备了创建、更新、删除工作流的能力请确保 API Key 的权限范围与使用场景匹配密钥勿入库config.toml中的 API Key 属于本地敏感配置不应提交到版本库。若你希望只读使用、彻底关闭破坏性操作仓库还提供了DISABLED_TOOLS与DISABLED_TOOL_OPERATIONS环境变量组合详见 README.md 的 Read-Only Deployment 一节与 HTTP_DEPLOYMENT.md可对管理工具做细粒度禁用。延伸阅读CLAUDE_CODE_SETUP.mdClaude Code CLI 的接入方式含.mcp.json项目级配置与作用域管理CURSOR_SETUP.md 与 WINDSURF_SETUP.mdCursor、Windsurf 等 IDE 的接入步骤ANTIGRAVITY_SETUP.mdAntigravityChat in IDE的mcp_config.json配置示例SELF_HOSTING.mdnpx、Docker、Railway 等自托管部署方式HTTP_DEPLOYMENT.md远程 HTTP 部署与只读部署方案SECURITY_HARDENING.md信任模型与加固选项。【免费下载链接】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），仅供参考