Codex MCP 异步服务器

用于OpenAI Codex CLI的异步MCP封装，节省95%的上下文

启用Claude Code以异步方式调用Codex（GPT-5），过滤掉思考过程以节省95%的上下文标记。

特性

• ✅ 异步执行 - 在后台启动Codex任务，继续工作
• ✅ 高效上下文 - 过滤思考/执行日志，仅返回核心结果
• ✅ 完全控制 - 访问所有Codex模型和推理努力
• ✅ 零配置 - 开箱即用与Claude Code

快速开始

🚀 使用UVX安装

无需配置 - 直接运行：

uvx codex-mcp-async

配置Claude Code

在你的 ~/.claude/settings.json 中添加：

{
  "mcpServers": {
    "codex-mcp": {
      "command": "uvx",
      "args": ["codex-mcp-async"],
      "env": {}
    }
  }
}

或使用提供的配置：复制 mcp-config.json 到你的Claude设置目录

重启Claude Code

重新加载或重启Claude Code以加载MCP服务器。

使用示例

🚀 异步执行（游戏规则改变者！）

启动一个长时间的Codex任务并立即继续工作：

你：

请分析整个代码库并生成全面的文档

Claude： 我将分析你的整个代码库并生成全面的文档。这是一个大型任务，所以我将异步启动它...

✅ 任务已启动（任务ID：abc12345） 你可以继续做其他事情，同时它在后台运行！

你：（立即继续工作）

当文档正在生成时，请帮我解决这个bug

Claude： 当然！让我帮你解决那个bug...

你：（几分钟后）

你能检查一下文档任务是否完成吗？

Claude： ✅ 文档已完成！

[查看生成的文档]

• API参考
• 代码示例
• 架构概述
• 设置说明

⚡ 并行执行

同时运行多个Codex任务：

你：

我需要同时做三件事：

1. 为utils.py生成单元测试
2. 将database.py重构为使用async/await
3. 为api.py中的所有函数添加类型提示

Claude： 我将同时启动这三个任务！

🔄 任务1已启动（任务ID：task1） - 生成单元测试 🔄 任务2已启动（任务ID：task2） - 重构数据库代码 🔄 任务3已启动（任务ID：task3） - 添加类型提示

所有任务都在并行运行...

你：（稍后）

这三个任务都完成了吗？

Claude： ✅ 全部完成！

• ✅ 任务1：为utils.py生成了单元测试
• ✅ 任务2：将database.py重构为异步模式
• ✅ 任务3：为api.py中的函数添加了类型提示

🎯 快速同步任务

对于简单的即时任务：

你：

编写一个Python函数来验证电子邮件地址

Claude：

import re

def validate_email(email):
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return re.match(pattern, email) is not None

# 使用示例
print(validate_email("user@example.com"))  # True
print(validate_email("invalid-email"))    # False

✅ 任务完成！

🧠 模型选择

你：

使用高推理能力的GPT-5分析这篇研究论文

Claude：

# 使用分析模型而不是编码模型
mcp__codex_mcp__codex_execute(
    prompt="分析这篇关于机器学习的研究论文",
    args=["--full-auto", "-m", "gpt-5", "--config", "model_reasoning_effort=high"]
)

为什么是异步+上下文过滤？

问题1： Codex在运行时会阻塞Claude Code。 问题2： Codex为每个任务输出3000+标记的思考日志。

解决方案： 此MCP服务器异步运行Codex，并过滤掉95%的噪音。

优点：

• 🚀 启动任务并立即继续工作
• ⚡ 并行运行多个任务
• 💾 95%上下文节省（3000个标记→150个标记）
• 🎯 仅返回干净、集中的结果
• 🧹 自动清理进程

高级用法

模型选择

gpt-5-codex（默认） - 最适合编码、调试、实现 gpt-5 - 最适合分析、规划、研究

推理级别

• minimal/low - 快速任务
• medium - 标准工作（默认）
• high - 复杂问题

示例配置

# 快速编码任务
args=["--full-auto", "--config", "model_reasoning_effort=low"]

# 复杂分析
args=["--full-auto", "-m", "gpt-5", "--config", "model_reasoning_effort=high"]

# 网络搜索+分析
args=["--full-auto", "--search", "-m", "gpt-5"]

架构与性能

Claude Code（你）
    ↓ 调用MCP工具
codex-mcp-async（在后台运行Codex）
    ↓ 过滤思考日志（节省95%！）
Codex CLI（GPT-5）
    ↓ 返回干净的结果
Claude Code（接收集中的输出）

上下文节省：

• 之前：3600个标记（思考+日志+结果）
• 之后：180个标记（仅干净的结果）
• 减少95%！

故障排除

服务器未显示？

• 检查：uvx codex-mcp-async 是否无错误运行
• 配置更改后重启Claude Code

任务卡在“运行中”？

• 大型任务需要时间完成
• 检查调试日志：/tmp/codex_mcp_debug.log

上下文过大？

• 启用过滤：对长时间任务始终使用异步模式
• 将大型任务拆分为较小的任务

要求

• Python 3.8+
• 安装并认证的Codex CLI
• Claude Code
• uvx（用于简单安装）

许可证

MIT许可证 - 查看LICENSE

---

问题？ 在GitHub上打开一个issue。

由❤️为Claude Code + Codex社区制作