AI精品店

Appearance

MCP 服务 ​

本页整理自 CodexZH 官方「MCP 服务配置」教程，补充了更清晰的分步与 Windows 排障提示。

1. 什么是 MCP ​

MCP（Model Context Protocol）是一种通用协议，用来让 AI 通过“工具/资源”扩展能力。Codex 作为 MCP 客户端，可以按需启动并调用你配置的 MCP 服务。

典型用途：

  • 文档检索（比如把最新框架文档接给 Codex）
  • 浏览器自动化（测试、页面操作）
  • 本地工具（文件系统、SQLite 等）

2. 推荐方式：命令行一键注册 MCP 服务 ​

CodexZH 教程推荐使用 codex mcp add 快速注册服务，适合试用与临时场景。

示例：添加 Context7 文档服务（官方教程示例）

bash
codex mcp add context7 -- npx -y @upstash/context7-mcp --api-key "your_api_key"

常用命令：

bash
codex mcp list
codex mcp remove context7

3. Windows 平台特别提示（非常重要） ​

CodexZH 官方教程指出：Windows 开发者如果直接照搬官方的 [mcp_servers] 示例，常会遇到运行失败。

常见错误信息 ​

  • Program not found
  • request timed out

Windows 下的处理思路 ​

  1. 在配置中把 command 指向真实的 npx.cmd 路径，例如： C:\Program Files\nodejs\npx.cmd

  2. 增加 env，至少包含 SYSTEMROOT，保证子进程能找到系统组件。

官方教程给出的配置示例（可直接抄，注意路径里的反斜杠写法）：

toml
[mcp_servers.context7]
command = "C:\\Program Files\\nodejs\\npx.cmd"
args = ["-y", "@upstash/context7-mcp", "--api-key", "your_api_key"]
env = { SYSTEMROOT = "C:\\Windows" }

官方教程也给了命令行“快速写法”（适合直接跑一次验证）：

bash
codex mcp add context7 --env SYSTEMROOT=C:\Windows -- "C:\Program Files\nodejs\npx.cmd" -y @upstash/context7-mcp --api-key "your_api_key"

4. 手动编辑 config.toml（适合团队共享/版本化） ​

当你希望把 MCP 配置纳入 dotfiles 或团队文档时，可以直接维护 ~/.codex/config.toml（Windows 同理）。

CodexZH 教程给出的“最小可用示例”（按需删改）：

toml
# ~/.codex/config.toml
model = "gpt-5-codex"
approval_policy = "untrusted"

[mcp_servers.filesystem]
command = "mcp-server-filesystem"
args = ["/path/to/workspace"]

[mcp_servers.sqlite]
command = "mcp-server-sqlite"
args = ["/path/to/database.db"]
startup_timeout_sec = 20

[mcp_servers.chrome]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]
startup_timeout_sec = 20

配置技巧（官方教程要点）：

  • 支持多个服务，按需新增 [mcp_servers.xxx]
  • Windows 路径请使用双反斜杠，例如：D:\\workspace

5. 远程 MCP（Streamable HTTP） ​

当 MCP 服务部署在云端或需要 OAuth 时，可以使用 URL 方式连接。CodexZH 教程示例：

  1. 启用实验性 RMCP 客户端：
toml
experimental_use_rmcp_client = true
  1. 配置远程服务：
toml
[mcp_servers.context7_http]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_MCP_TOKEN"

补充说明（官方教程要点）：

  • bearer_token_env_var：从环境变量读取令牌
  • startup_timeout_sec：服务启动超时（默认 10s）
  • 若使用 OAuth，请先执行 codex mcp login server_name 完成登录，再回到 Codex 中使用

6. 推荐的 MCP 服务（官方教程精选） ​

6.1 Context7（开发文档查询） ​

toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 15

6.2 Chrome DevTools（浏览器控制） ​

toml
[mcp_servers.chrome]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]
startup_timeout_sec = 20