MMCPMarkets
WC

w31r4/codex-mcp-go

Developer tools
52 stars 0 forks Quality 90 Trend 90
Repository Install

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

Overview

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

README

codex-mcp-go

简介

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:

# 使用 npm 安装 (推荐)
npm i -g @openai/codex

# 或者参考官方仓库
# https://github.com/openai/codex-cli

2. 安装 MCP Server

方式一：使用 npx (推荐)

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

npx @zenfun510/codex-mcp-go

方式二：手动下载

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

方式三：源码构建

需要 Go 1.24+ 环境。

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

3. 配置 MCP 客户端

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

方式 A：使用 npx (推荐)

方式 B：使用本地二进制文件

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

4. 验证

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 配置文件 或 环境变量 调整运行策略。优先级：默认值 < 配置文件 < 环境变量。

./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 配置或作为任务的初始指令：

2. 辅助编程模式

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

工具参数说明

工具名称：codex

参数 类型 必填 默认值 说明
PROMPT string ✅ - 发送给 Codex 的指令
cd string ✅ - 工作目录路径
sandbox string ❌ "read-only" 策略：read-only / workspace-write / danger-full-access
SESSION_ID string ❌ "" 会话 ID，用于多轮对话
skip_git_repo_check bool ❌ true 允许在非 Git 目录运行
return_all_messages bool ❌ false 返回完整推理日志
image []string ❌ [] 附加图片路径
model string ❌ "" 默认禁止，除非显式允许
yolo bool ❌ false 跳过所有确认（非交互）
profile string ❌ "" 默认禁止，除非显式允许
timeout_seconds int ❌ 1800 Codex 调用的总超时（秒，最多 1800）
no_output_seconds int ❌ 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 CLI CodexMCP (本工具)
基本 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 集成方面所做的开创性工作。

View this README on GitHub

Install

npx -y @zenfun510/codex-mcp-go

Configuration

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