Codex Mcp Server

Codex MCP Server

连接 Claude/Cursor 与 Codex CLI 的 MCP 服务。支持通过 @ 文件引用进行代码分析、多轮对话、沙箱编辑以及结构化变更模式。

功能特性

• 文件分析 — 使用 @src/、@package.json 语法引用文件
• 多轮会话 — 借助工作区隔离实现对话连续性
• 原生恢复 — 使用 codex resume 保留上下文（CLI v0.36.0+）
• 本地开源模型 — 通过 localProvider 使用 Ollama 或 LM Studio 运行
• 网络搜索 — 通过 search: true 启用研究能力
• 沙箱模式 — 借助显式沙箱与审批策略实现安全自动化
• 变更模式 — 为重构提供结构化 OLD/NEW 补丁输出
• 头脑风暴 — SCAMPER、设计思维、横向思维框架
• 健康诊断 — CLI 版本、功能与会话监控
• 跨平台 — 全面支持 Windows、macOS、Linux

快速开始

claude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-tool

前置条件： Node.js 18+、已安装并完成认证的 Codex CLI。

配置

{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "@trishchuk/codex-mcp-tool"]
    }
  }
}

配置位置： macOS：~/Library/Application Support/Claude/claude_desktop_config.json | Windows：%APPDATA%\Claude\claude_desktop_config.json

使用示例

// File analysis
'explain the architecture of @src/';
'analyze @package.json and list dependencies';

// With specific model
'use codex with model gpt-5.6-sol to analyze @algorithm.py';

// Multi-turn conversations (v1.4.0+)
'ask codex sessionId:"my-project" prompt:"explain @src/"';
'ask codex sessionId:"my-project" prompt:"now add error handling"';

// Brainstorming
'brainstorm ways to optimize CI/CD using SCAMPER method';

// Sandbox mode
'use codex sandbox:true to create and run a Python script';

// Web search
'ask codex search:true prompt:"latest TypeScript 5.7 features"';

// Local OSS model (Ollama)
'ask codex localProvider:"ollama" model:"qwen3:8b" prompt:"explain @src/"';

工具

工具	描述
ask-codex	使用文件、模型、会话和安全控制执行 Codex CLI
batch-codex	按顺序或并发运行多个原子 Codex 任务
review-changes	运行原生非交互式 Codex 审查命令
do-act	执行、通过 shell 命令验证，并重试修复
image-gen	使用 Codex 内置的 image_gen 工具生成或编辑图像
brainstorm	使用结构化创意框架生成想法
list-sessions	查看、删除或清除 MCP 对话映射
list-skills	列出所选工作区中可见的技能
health	诊断 CLI 安装、版本、功能和会话
fetch-chunk	从缓存的变更模式输出中获取一个分块
ping	测试 MCP 连接
help	返回当前的 codex --help 输出
version	报告 Codex CLI、Node.js、平台和软件包版本
timeout-test	测试保活和超时行为

图像生成

image-gen 驱动 Codex 内置的 image_gen 工具，因此它会使用你的 ChatGPT 登录信息，且不需要 OPENAI_API_KEY。该工具只接受提示词和参考图像路径：由 Codex 选择图像模型和像素尺寸，并且没有尺寸、质量、格式或蒙版参数。因此，image-gen 将所有引导信息都放入一个结构化提示词中（用例、资产类型、风格、构图、确切文本、参考角色、编辑不变量、宽高比、预设），并指示 Codex 宿主模型转发该提示词，而不是即兴发挥。

// New image, 16:9, exact Cyrillic headline, copied into the project
'image-gen prompt:"YouTube cover about AI coding agents" aspect:"wide" text:"АГЕНТИ БЕЗ ХАОСУ" presets:["thumbnail","exact-text"] outputPath:"assets/cover.png"';

// Edit: change only the headline, keep everything else
'image-gen editImage:"assets/cover.png" prompt:"Replace the headline text" text:"ЧАСТИНА 2" preserve:["people and background"] outputPath:"assets/cover.png"';

图像由 Codex 保存在 $CODEX_HOME/generated_images/<thread>/ 下，并在提供 outputPath 时复制到该路径；如果文件已存在则保留原文件，并将副本写为带 -v2 后缀的同级文件，除非设置 overwrite: true。结果会报告每个文件的尺寸和 alpha 通道，因此如果 transparentBackground 请求返回的是不透明图像，就会被标记出来。

模型

默认情况下，model 参数会被省略，Codex CLI 会应用你 ~/.codex/config.toml 中的默认模型（例如 model = "gpt-6.1-sol"）。仅当你需要为单次调用覆盖已配置的默认值时才传入 model。推理深度按工具进行校准：

• ask-codex — 使用 Codex CLI 默认推理（medium）。仅当任务需要更多规划或检查时才提高它。
• brainstorm、do-act、review-changes — 默认 reasoningEffort: "high"（创意构思、执行-检查-修复循环以及代码审查都能从更深入的推理中受益）。

模型	建议
gpt-6.1-sol	用于编码和日常工作 的最新主力模型（CLI 0.159+）
gpt-6-astra	面向最高要求工作的前沿智能
gpt-6-sol	上一代主力模型
gpt-6-luna	快速且经济；适合更简单、可重复的任务
gpt-5.6-sol	较老一代主力模型
gpt-5.6-terra	面向简单工作的较老平衡模型
gpt-5.6-luna	较老的快速、高效模型
gpt-5.5	旧版 — Codex 会引导调用方使用 gpt-5.6-sol

Sol、Astra 和 Terra 模型暴露 max 和 ultra 推理；Luna 模型最高到 max，而 gpt-5.5 最高到 xhigh。ultra 可能会将工作委派给子 Agent；大多数任务应保持在 medium 或 high。传入具体的 slug — 裸的动态别名 gpt-6 和 gpt-5.6 会被 API 拒绝。gpt-6.1-sol 会被 Codex CLI 0.157.x 拒绝，并返回与未知 slug 相同的 400；请使用 npm install -g @openai/codex@latest 升级。

主要特性

会话管理（v1.4.0+）

具有工作区隔离的多轮对话：

{ "prompt": "analyze code", "sessionId": "my-session" }
{ "prompt": "continue from here", "sessionId": "my-session" }
{ "prompt": "start fresh", "sessionId": "my-session", "resetSession": true }

环境变量：

• CODEX_SESSION_TTL_MS - 会话 TTL（默认：24h）
• CODEX_MAX_SESSIONS - 最大会话数（默认：50）

Codex CLI 版本

需要 Codex CLI 0.95.0 或更新版本。在较旧版本上，服务会失败并给出明确的升级消息，而不是静默丢弃不支持的标志。使用 npm install -g @openai/codex@latest 升级；运行 health 工具可查看检测到的版本。

故障排除：“codex not found”

从 GUI（Dock、Finder、开始菜单）启动的 MCP 客户端会继承一个最小化的 PATH，其中不包含 Homebrew、nvm 和 volta 目录，因此 codex 可能在终端中可用，但在应用中不可用。服务会自动搜索这些位置；如果仍然找不到 CLI，请显式固定它：

{ "env": { "CODEX_CLI_PATH": "/opt/homebrew/bin/codex" } }

使用 which codex 找到该值。运行 health 工具可查看解析到了哪个可执行文件以及如何解析的。

本地 OSS 模型（v1.6.0+）

使用本地 Ollama 或 LM Studio 运行，而不是 OpenAI：

// Ollama
{ "prompt": "analyze @src/", "localProvider": "ollama", "model": "qwen3:8b" }

// LM Studio
{ "prompt": "analyze @src/", "localProvider": "lmstudio", "model": "my-model" }

// Auto-select provider
{ "prompt": "analyze @src/", "oss": true }

要求： 本地运行 Ollama，并使用支持工具调用的模型（例如 qwen3:8b）。

高级选项

参数	描述
model	模型选择
sessionId	启用对话连续性
sandbox	兼容性自动化：workspace-write + never
search	启用网页搜索
changeMode	结构化 OLD/NEW 编辑
addDirs	额外的可写目录
toolOutputTokenLimit	限制响应详细程度（100-10,000）
reasoningEffort	low、medium、high、xhigh、max、ultra
oss	使用本地 OSS 模型提供方
localProvider	本地提供方：lmstudio 或 ollama
strictConfig	遇到未知的 Codex 配置键时报错
ephemeral	不持久化 Codex 会话文件
ignoreUserConfig	忽略 $CODEX_HOME/config.toml
ignoreRules	忽略 execpolicy .rules 文件

CLI 兼容性

已针对 Codex CLI 0.144.3 验证。服务保留了较旧功能的防护， 但建议使用当前版本。当前值得注意的行为：

• Codex CLI 已移除 --full-auto 和审批策略 on-failure。
• MCP sandbox: true / fullAuto: true 仍是 --sandbox workspace-write --ask-for-approval never 的兼容别名；它们不会绕过沙箱。
• 原生 --search 在不再使用已弃用的 web_search_request 功能的情况下使用。
• 当前的 exec 标志包括 --strict-config、--ephemeral、 --ignore-user-config 和 --ignore-rules。

故障排除

codex --version    # Check CLI version
codex login        # Authenticate

使用 health 工具进行诊断：'use health verbose:true'

迁移

v2.5.x → v2.6.0： Codex CLI 0.159.2 模型同步以及新的 image-gen 工具。 新增 gpt-6.1-sol（需要 Codex CLI 0.159+）、gpt-6-sol 和 gpt-6-luna。 破坏性变更： 移除了 gpt-5.4-mini，它现在会返回 HTTP 400。

v2.4.x → v2.5.0： Codex CLI 0.153.4 兼容性调整；新增 gpt-6-astra。破坏性变更： 移除了 gpt-5.4 和移动别名 gpt-5.6 （两者现在都会被拒绝并返回 HTTP 400），并移除了 untrusted 审批策略， Codex CLI 0.153.x 不再解析该策略。

v2.3.x → v2.4.0： Codex CLI 0.144.3 兼容性审计；新增 GPT-5.6 Sol/Terra/Luna、max/ultra 推理、当前 exec 标志、仅原生搜索， 以及对已移除的 --full-auto 标志和 on-failure 审批策略的安全兼容处理。

v2.2.x → v2.3.0： gpt-5.5 成为新的默认模型，新增 gpt-5.4-mini，移除了已退役模型（gpt-5.3-codex-spark、gpt-5.2-codex、gpt-5.1-codex-max、gpt-5.1-codex-mini）。

v2.0.x → v2.1.0： gpt-5.4 成为新的默认模型，更新了回退链。

v1.5.x → v1.6.0： 本地 OSS 模型支持（localProvider、oss）、gpt-5.3-codex 默认模型、xhigh 推理强度。

v1.3.x → v1.4.0： 新增 sessionId 参数、list-sessions/health 工具、结构化错误处理。无破坏性变更。

许可证

MIT 许可证。与 OpenAI 无附属关系。

---

文档 | 问题 | 灵感来自 jamubc/gemini-mcp-tool