【Bug已解决】Codex 报错 MCP client for context7 failed to start: program not found 解决方案1. 问题描述按照某篇教程给 Codex CLI 配置 context7 这个 MCP 服务器编辑好~/.codex/config.toml保存后启动 Codex 时收到报错Error: MCP client for context7 failed to start: program not found1.1 具体现象配置文件内容看起来和教程完全一致照抄了command npx这样的写法在终端里手动执行npx -y upstash/context7-mcp却完全正常换一台电脑同样的配置反而能正常工作Windows 用户遇到的概率明显更高这个问题的本质是Codex 启动 MCP 子进程时的命令查找机制和终端手动执行命令时不完全一致尤其是在 Windows 上直接写command npx很容易触发程序找不到的问题。2. 原因分析MCPModel Context Protocol服务器本质上是一个由 Codex 启动的独立子进程Codex 需要知道该用什么命令、带什么参数来启动这个子进程。当配置里写的command字段是一个简短的命令名如npx而不是完整路径时Codex 内部的子进程启动逻辑需要在系统 PATH 中查找这个命令——而这个查找过程在 Windows 上对.cmd/.ps1这类 npm 生成的包装脚本的处理方式与 Unix 系终端的行为存在差异。用一张流程图梳理排查方向Codex 读取 mcp_servers 配置中的 command 字段 ↓ 尝试启动子进程如 npx -y upstash/context7-mcp ↓ 是否能正确定位并执行该命令 ├─ 能 → MCP 服务器正常启动 └─ 不能 → program not found ↓ 常见于 Windows 上简短命令名如 npx未被正确解析3. 解决方案方案一改用完整的可执行文件绝对路径社区验证最有效不要在配置里写简短的命令名而是找到 Node.js 和对应 npm 包的真实绝对路径直接写全# ~/.codex/config.toml # 有问题的写法 [mcp_servers.context7] command npx args [-y, upstash/context7-mcp, --api-key, 你的密钥] # 修正后的写法Windows 示例路径请替换为实际安装位置 [mcp_servers.context7] command C:\\Program Files\\nodejs\\node.exe args [ C:\\Users\\yourname\\AppData\\Roaming\\npm\\node_modules\\upstash\\context7-mcp\\dist\\index.js, --api-key, 你的密钥 ]先用where nodeWindows或which nodemacOS/Linux确认 Node.js 的真实路径再定位对应 MCP 包的实际入口文件位置。方案二确认 npx 对应的包是否已经预先安装npx在没有本地缓存的情况下会临时下载并执行包这个过程涉及网络请求如果失败可能被误判为program not found。建议提前手动全局安装该 MCP 包减少运行时的不确定性npm install -g upstash/context7-mcp安装完成后配置里直接指向全局安装后的实际入口文件路径而不是依赖npx临时下载执行。方案三Windows 上尝试显式使用.cmd后缀[mcp_servers.context7] command npx.cmd args [-y, upstash/context7-mcp, --api-key, 你的密钥]有些环境下仅仅是把npx改成npx.cmd就能让 Windows 正确识别并执行该命令。方案四查看更详细的调试日志确认具体失败环节codex --debug 测试 context7 MCP 连接打开调试日志能看到 Codex 具体尝试执行的完整命令和失败时的系统返回信息比单纯看到program not found这一句话更容易定位真实原因。方案五用 shell 包装脚本统一封装启动命令如果需要同时兼容多个平台可以自己写一个简单的启动脚本在脚本内部处理好平台差异配置文件里只需要指向这个统一的脚本入口[mcp_servers.context7] command /path/to/start-context7.sh4. 各方案对比总结方案适用场景推荐指数改用绝对路径Windows 上最常见、最有效的解决方式⭐⭐⭐⭐⭐提前全局安装避免依赖 npx减少运行时网络下载的不确定性⭐⭐⭐⭐使用 .cmd 后缀Windows 平台快速尝试⭐⭐⭐⭐开启调试日志需要更精确定位失败原因⭐⭐⭐⭐统一封装启动脚本需要跨平台兼容多个 MCP 服务⭐⭐⭐5. 常见问题 FAQ5.1 为什么同样的 npx 写法在 Claude Code 里配置 MCP 服务器完全正常不同工具对子进程启动的底层实现方式不完全相同Claude Code 在这方面的兼容性处理可能更完善。遇到 Codex 报错时不要假设能在别的工具里用就一定没问题直接按 Codex 自己的排查方式处理即可。5.2 配置了多个 MCP 服务器只有其中一个报错其他正常说明什么说明问题很可能不在 Codex 本身而在于这个特定 MCP 服务器的启动命令写法比如恰好用了简写的npx可以对比正常工作的其他 MCP 服务器配置看它们的command字段是否用了绝对路径。5.3 macOS/Linux 上是否也会遇到这个问题概率相对较低但如果系统的 PATH 环境变量配置不完整比如 Codex 客户端继承的环境变量和终端不一致同样可能出现命令查找失败的情况排查思路可以参考本文的方案一和方案四。5.4 有没有办法批量检查所有已配置的 MCP 服务器是否都能正常启动可以写一个简单的自查脚本逐一手动执行配置文件中各个 MCP 服务器对应的commandargs组合确认每一条命令在当前环境下都能被正确找到和执行。5.5 排查清单速查表□ 1. 确认报错的具体是哪个 MCP 服务器配置项 □ 2. 用 where/which 命令确认对应可执行文件的真实绝对路径 □ 3. 尝试把配置中的简写命令名改为完整绝对路径 □ 4. 考虑提前全局安装该 MCP 包避免依赖 npx 临时下载 □ 5. Windows 平台尝试显式加上 .cmd 后缀 □ 6. 打开 --debug 日志获取更详细的失败信息6. 总结MCP client failed to start: program not found报错的本质是Codex 启动 MCP 子进程时无法正确定位配置文件中写的简写命令名对应的可执行文件尤其容易发生在 Windows 平台上使用npx这类简写命令的场景。核心处理思路把配置中的命令改为完整的绝对路径是社区验证最有效的解决方式提前全局安装依赖的 MCP 包减少npx临时下载带来的不确定性善用--debug调试日志获取比一句简单报错更详细的失败上下文。最佳实践建议给 Codex 配置任何涉及子进程启动的 MCP 服务器时优先直接写明确的绝对路径而不是依赖系统 PATH 的隐式查找能从源头规避这类跨平台命令解析差异带来的问题。