AI精品店

Appearance

MCP 服务 ​

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

1. 什么是 MCP ​

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

典型用途：

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

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

用 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 平台特别提示 ​

直接照搬官方的 [mcp_servers] 示例在 Windows 上常会运行失败。

常见错误：

  • Program not found
  • request timed out

处理方式：

  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 同理）。

最小可用示例：

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 方式连接。

  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