Codex MCP Go

io.github.w31r4由 GitHub 账号 w31r4 发布v0.2.1更新于 Oct 24, 2026

MCP server wrapping Codex CLI for stdio-based tool calls.

已验证STDIO仅桌面开发者工具AI 与机器学习

概览

AI 生成的概览

把 OpenAI Codex CLI 封装成一个 MCP 工具，让助手把编码、调试和代码审查任务交给 Codex 执行。

可以做什么
  • 向 Codex 下发编码任务：提示词加工作目录，可选模型、配置档、图片和超时。
  • 复用返回的会话 ID 进行多轮对话。
  • 用只读、工作区可写、完全访问等沙箱模式控制执行范围，并可跳过审批。
  • 获取完整推理与工具调用日志，或只取最终结果。
  • 通过 TOML 配置文件或环境变量调整允许的模型、沙箱模式和工作目录等策略。
适用场景
适合让擅长规划的助手把棘手的实现、Bug 修复或代码审查交给 Codex，或在自行改代码前先取得 Codex 的评审意见和 diff 形式原型。
运行要求
以 stdio 方式在本机运行。需要已安装并配置好的 OpenAI Codex CLI；使用 npx 包需 Node.js，也可用预编译二进制，或用 Go 1.24+ 从源码构建。README 的客户端配置在服务器环境中设置 OPENAI_API_KEY。
安装前请注意
该工具可让 Codex 以可写或完全访问模式运行，yolo 选项会跳过所有确认，因此工作目录中的代码和文件可能被修改。默认是只读且关闭 yolo，但模型和配置档默认被拒绝，需显式放行。API 密钥通过 OPENAI_API_KEY 传入，提示词和代码会发送到 OpenAI 的 Codex 服务。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Codex MCP Go，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

codex-mcp-go

Codex CLI 的 MCP 协议封装实现

[License: MIT] [Go Version] [MCP Compatible] [NPM Version]

⭐ 如果觉得好用，请给个 Star 吧！您的支持是我们更新的动力~ ⭐

English | 简体中文

简介

codex-mcp-go 是一个基于 Go 语言实现的 MCP (Model Context Protocol) 服务器。它封装了 OpenAI 的 Codex CLI，使其能够作为 MCP 工具被 KiloCode、Roo Code、Cline 等各种 "Vibe Coding" AI 客户端调用。

这个项目的初衷很简单：让强者更强，让专才专用。

在我自己的工作流中（在 KiloCode 里使用 Gemini 3.0 Pro），我发现像 Gemini 这样的先进模型拥有强大的规划能力和想象力，但在修复自己生成的复杂代码时偶尔会“卡壳”。而 Codex，这位老练的“代码老师傅”，虽然在宏大叙事上稍逊一筹，但在具体的代码实现、Bug 修复和遵循精确指令方面却无人能及。

所以，为什么不让它们合作呢？

受到 codexmcp (Python 实现) 的启发，我决定用我更喜欢的 Go 语言，边学 mcp-go-sdk 边重复造了这个轮子，主要目的是练手并打造一个更适合我自己的工具。

现在，你可以用一句话，在任何支持 MCP 的 Vibe Coding 工具中，让 Gemini 或 Claude 这样的“总指挥”去调用 Codex 这个“特种兵”来完成最棘手的编码任务。

主要特性：

  • 会话管理：支持 SESSION_ID 维持多轮对话上下文。
  • 沙箱控制：提供 read-only、workspace-write 等安全策略。
  • 并发支持：基于 Go 协程，支持多客户端并发调用。
  • 单文件部署：编译为单一二进制文件，无运行时依赖。

快速开始

1. 前置要求

本工具依赖 OpenAI 的 codex CLI。请确保您已安装并配置好它。

安装 Codex CLI:

bash
# 使用 npm 安装 (推荐)npm i -g @openai/codex
# 或者参考官方仓库# https://github.com/openai/codex-cli

2. 安装 MCP Server

方式一：使用 npx (推荐)

无需安装 Go 环境，直接运行：

bash
npx @zenfun510/codex-mcp-go
方式二：手动下载

从 Releases 页面下载对应平台的二进制文件。

方式三：源码构建

需要 Go 1.24+ 环境。

bash
git clone https://github.com/w31r4/codex-mcp-go.gitcd codex-mcp-gogo build -o codex-mcp-go cmd/server/main.go

3. 配置 MCP 客户端

根据您使用的 AI 客户端，选择对应的配置方式。

方式 A：使用 npx (推荐)
Claude Code
bash
claude mcp add codex -s user --transport stdio -- npx -y @zenfun510/codex-mcp-go
Roo Code (VSCode / Cursor)

在 Roo Code 的 MCP 设置中添加：

json
{  "mcpServers": {    "codex": {      "command": "npx",      "args": ["-y", "@zenfun510/codex-mcp-go"],      "env": {        "OPENAI_API_KEY": "your-api-key"      }    }  }}

配置文件路径参考：

  • VSCode: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
  • Cursor: ~/.config/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
KiloCode

在 ~/.kilocode/mcp.json 中添加：

json
{  "mcpServers": {    "codex": {      "command": "npx",      "args": ["-y", "@zenfun510/codex-mcp-go"],      "env": {        "OPENAI_API_KEY": "your-api-key"      }    }  }}
Cursor (Native MCP)
  1. 打开 Cursor 设置 -> Features -> MCP
  2. 点击 "Add New MCP Server"
  3. 填写配置：
    • Name: codex
    • Type: stdio
    • Command: npx
    • Args: -y @zenfun510/codex-mcp-go
方式 B：使用本地二进制文件

如果您已通过 go build 构建了二进制文件（假设路径为 /path/to/codex-mcp-go），可使用以下配置：

Claude Code
bash
claude mcp add codex -s user --transport stdio -- /path/to/codex-mcp-go
Roo Code / KiloCode / 通用 JSON 配置
json
{  "mcpServers": {    "codex": {      "command": "/path/to/codex-mcp-go",      "args": [],      "env": {        "OPENAI_API_KEY": "your-api-key"      }    }  }}
Cursor (Native MCP)
  1. 打开 Cursor 设置 -> Features -> MCP
  2. 点击 "Add New MCP Server"
  3. 填写配置：
    • Name: codex
    • Type: stdio
    • Command: /path/to/codex-mcp-go
    • Args: (留空)

4. 验证

bash
cat <<'EOF' | ./codex-mcp-go{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{}}}{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}EOF

需先完成 initialize 握手，然后才能调用 tools/list。若返回包含 codex 工具的 JSON 数据，即表示运行正常。

5.（可选）服务端配置（配置文件 + 环境变量）

支持通过 TOML 配置文件 或 环境变量 调整运行策略。优先级：默认值 < 配置文件 < 环境变量。

bash
./codex-mcp-go --config ./codex-mcp.example.toml# 或CODEX_MCP_CONFIG=./codex-mcp.example.toml ./codex-mcp-go

环境变量（会覆盖配置文件）：

  • CODEX_MCP_SERVER_NAME / CODEX_MCP_VERSION
  • CODEX_DEFAULT_TIMEOUT / CODEX_MAX_TIMEOUT / CODEX_NO_OUTPUT_TIMEOUT（单位：秒）
  • CODEX_MAX_BUFFERED_LINES / CODEX_EXECUTABLE_PATH
  • CODEX_ALLOWED_MODELS / CODEX_ALLOWED_PROFILES（逗号分隔；* 表示允许任意值；默认空=全部拒绝）
  • CODEX_DEFAULT_SANDBOX / CODEX_ALLOWED_SANDBOX_MODES（逗号分隔）
  • CODEX_ALLOWED_WORK_DIRS（逗号分隔的目录前缀列表；空=不限制）
  • CODEX_DISABLE_YOLO（true/false）
  • CODEX_LOG_LEVEL / CODEX_LOG_FORMAT / CODEX_LOG_OUTPUT / CODEX_LOG_FILE

推荐的系统提示词 (System Prompts)

为了获得最佳体验，建议根据您使用的客户端类型配置相应的系统提示词。

1. 智能体模式 (KiloCode / Roo Code / Cline / Claude Code)

适用于能够自主规划和执行多步任务的 Agent。

对于 KiloCode / Roo Code / Cline 用户： 本项目提供了针对不同客户端的预配置专家模式文件。请根据您使用的客户端选择对应的文件导入：

导入后，您将获得经过调优的 "Codex 协作专家" 模式，该模式已针对您的客户端进行了身份认同适配。

对于 Claude Code 或手动配置： 请将以下内容添加到您的 Agent 配置或作为任务的初始指令：

点击展开详细提示词
text
## Core Instruction for CodeX MCP
在任何时刻，你必须思考当前过程可以如何与codex进行协作，如何调用Codex 为你提供的MCP工具作为你客观全面分析的保障。其中你**务必执行**以下几个步骤：**1** 在你对用户需求形成初步分析后，将用户需求、初始思路告知codex，并要求其完善需求分析和实施计划。**2** 在实施具体编码任务前，**必须向codex索要代码实现原型（要求codex仅给出unified diff patch，严禁对代码做任何真实修改）**。在获取代码原型后，你**只能以此为逻辑参考，再次对代码修改进行重写**，形成企业生产级别、可读性极高、可维护性极高的代码后，才能实施具体编程修改任务。**3** 无论何时，只要完成切实编码行为后，**必须立即使用codex review代码改动和对应需求完成程度**。**4** codex只能给出参考，你**必须有自己的思考，甚至需要对codex的回答提出置疑**。尽信书则不如无书，你与codex的最终使命都是达成统一、全面、精准的意见，所以你们必须不断争辩已找到通向真理的唯一途径。
## Codex Tool Invocation Specification
1. 工具概述   codex MCP 提供了一个工具 `codex`，用于执行 AI 辅助的编码任务。该工具**通过 MCP 协议调用**，无需使用命令行。
2. 工具参数   **必选**参数：   - PROMPT (string): 发送给 codex 的任务指令   - cd (Path): codex 执行任务的工作目录根路径
   可选参数：   - sandbox (string): 沙箱策略，可选值：     - "read-only" (默认): 只读模式，最安全     - "workspace-write": 允许在工作区写入     - "danger-full-access": 完全访问权限   - SESSION_ID (UUID | null): 用于继续之前的会话以与codex进行多轮交互，默认为 None（开启新会话）   - skip_git_repo_check (boolean): 是否允许在非 Git 仓库中运行，默认 False   - return_all_messages (boolean): 是否返回所有消息（包括推理、工具调用等），默认 False   - image (List[Path] | null): 附加一个或多个图片文件到初始提示词，默认为 None   - model (string | null): 指定使用的模型，默认为 None（使用用户默认配置）   - yolo (boolean | null): 无需审批运行所有命令（跳过沙箱），默认 False   - profile (string | null): 从 `~/.codex/config.toml` 加载的配置文件名称，默认为 None（使用用户默认配置）
3. 调用规范   **必须遵守**：   - 每次调用 codex 工具时，必须保存返回的 SESSION_ID，以便后续继续对话   - cd 参数必须指向存在的目录，否则工具会静默失败   - 严禁codex对代码进行实际修改，使用 sandbox="read-only" 以避免意外，并要求codex仅给出unified diff patch即可
   推荐用法：   - 如需详细追踪 codex 的推理过程和工具调用，设置 return_all_messages=True   - 对于精准定位、debug、代码原型快速编写等任务，优先使用 codex 工具

2. 辅助编程模式

适用于作为 IDE 插件运行的助手。建议添加到 .clinerules (Roo Code) 或 "Rules for AI" (Cursor) 中：

点击展开规则提示词
text
# Codex MCP Tool Rules
You have access to the `codex` tool, which wraps the OpenAI Codex CLI. Use it for complex code generation, debugging, and analysis.
## Workflow1.  **Consultation**: Before writing complex code, ask Codex for a plan or analysis.2.  **Prototyping**: Ask Codex for a `unified diff patch` to solve the problem.    *   **IMPORTANT**: Always use `sandbox="read-only"` when asking for code.    *   **IMPORTANT**: Do NOT let Codex apply changes directly.3.  **Implementation**: Read the Codex-generated diff, understand it, and then apply the changes yourself using your own file editing tools.4.  **Review**: After applying changes, you can ask Codex to review the code.
## Tool Usage-   **Session**: Always capture and reuse `SESSION_ID` for multi-turn tasks.-   **Path**: Ensure `cd` is set to the current workspace root.-   **Safety**: Default to `sandbox="read-only"`. Only use `workspace-write` if explicitly instructed by the user and you are confident in the operation.

工具参数说明

工具名称：codex

参数类型必填默认值说明
PROMPTstring✅-发送给 Codex 的指令
cdstring✅-工作目录路径
sandboxstring❌"read-only"策略：read-only / workspace-write / danger-full-access
SESSION_IDstring❌""会话 ID，用于多轮对话
skip_git_repo_checkbool❌true允许在非 Git 目录运行
return_all_messagesbool❌false返回完整推理日志
image[]string❌[]附加图片路径
modelstring❌""默认禁止，除非显式允许
yolobool❌false跳过所有确认（非交互）
profilestring❌""默认禁止，除非显式允许
timeout_secondsint❌1800Codex 调用的总超时（秒，最多 1800）
no_output_secondsint❌0无输出达到该秒数后终止运行（0 表示关闭）

运行时行为： 默认 30 分钟总超时（上限 30 分钟），无输出看门狗默认关闭；出现错误行、非零退出会携带最近输出返回，便于定位卡住原因。若网络慢或 MCP 客户端自身有较短的 RPC 超时，调用时保持 timeout_seconds=1800，以避免过早被取消。 默认策略： sandbox=read-only、yolo=false、skip_git_repo_check=false；model/profile 默认拒绝，需显式放行；timeout_seconds=1800（最多 1800）、no_output_seconds=0（关闭）。

功能对比

1. 与官方 Codex CLI 对比

特性官方 Codex CLICodexMCP (本工具)
基本 Codex 调用✅✅
多轮对话❌✅ (通过 Session 管理)
推理详情追踪❌✅ (完整日志捕获)
并行任务支持❌✅ (MCP 协议支持)
错误处理❌✅ (结构化错误返回)

2. 与 Python 版本 (codexmcp) 对比

特性Go 版本 (codex-mcp-go)Python 版本 (codexmcp)
部署单二进制文件，零依赖需 Python 环境及依赖
启动速度🚀 极快🐢 较慢 (解释器启动)
资源占用📉 低📈 较高
并发模型Goroutine (高效)Threading
适用场景生产环境、底层服务二次开发、原型验证

故障排查

  • 连接失败：检查 codex CLI 是否在 PATH 中，或确认 Go 版本 >= 1.24。
  • 无权限：检查二进制文件是否有执行权限 (chmod +x)。
  • Session 丢失：确保客户端正确传递了上一次调用返回的 SESSION_ID。

开源协议

本项目采用 MIT License 开源协议。

致谢

本项目深受 codexmcp (Python 实现) 的启发。感谢 GuDaStudio 团队在探索 Codex MCP 集成方面所做的开创性工作。

再次感谢您的关注！别忘了点个 Star 哦~ 🌟

来源：README.md，提交 524a8a1

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.2.1最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分