Codex MCP Swarm

codex mcp群

一个MCP服务器，将OpenAI的Codex CLI封装在一起 真正的并行执行 和 实时任务监控.零依赖性——单个Python文件，仅限stdlib。

为什么？

官方的 codex mcp-server 按顺序处理请求。如果您的MCP客户端（Claude Code等）需要运行5个Codex任务，它们会一个接一个地排队。此服务器将每个任务生成为一个独立的子进程，因此它们并行运行。

其他Codex MCP包装器没有的独特功能：

• 工作树隔离 -- worktree: true 为每个任务创建一个隔离的git工作树，这样并行的Codex实例就不会相互编辑
• 批量等待 --启动N个任务，调用 codex_wait 一旦完成，即可获得所有结果
• 实时状态 --查看每个Codex任务现在正在做什么（上次工具调用、当前推理、进度）
• 全标志奇偶校验 --与官方Codex MCP工具相同的参数(sandbox, approval-policy, cwd, model, config等等）
• 插入配置 --接受相同 -c key=value 服务器参数为 codex mcp-server

工具

安装

克劳德代码

claude mcp add codex-swarm -- uvx --upgrade codex-mcp-swarm \
  -c model=gpt-5.4 \
  -c approval_policy=never \
  -c sandbox_mode=danger-full-access \
  --skip-git-repo-check

就是这样。没有克隆，没有设置。 uvx 直接从PyPI下载并运行它。这 --upgrade 标志确保您在重新启动时始终获得最新版本。

注： 需要 紫外线 (curl -LsSf https://astral.sh/uv/install.sh | sh).或者，使用 pipx run codex-mcp-swarm 而不是 uvx codex-mcp-swarm.

手册(~/.claude.json)

{
  "mcpServers": {
    "codex-swarm": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--upgrade",
        "codex-mcp-swarm",
        "-c", "model=gpt-5.4",
        "-c", "approval_policy=never",
        "-c", "sandbox_mode=danger-full-access",
        "--skip-git-repo-check"
      ]
    }
  }
}

这 -c 标志与 codex mcp-server --复制粘贴您现有的配置。

用法

并行执行

1. Call codex_async with prompt A  -->  task_id: "abc123"
2. Call codex_async with prompt B  -->  task_id: "def456"
3. Call codex_async with prompt C  -->  task_id: "ghi789"
4. Call codex_wait(task_ids=["abc123", "def456", "ghi789"])
   --> blocks until all finish, returns all results

工作树隔离

防止并行任务编辑相同的文件：

1. Call codex_async(prompt="Refactor auth", worktree=true)
   --> task_id: "abc123"
   --> Worktree Branch: codex-swarm/abc123

2. Call codex_async(prompt="Add logging", worktree=true)
   --> task_id: "def456"
   --> Worktree Branch: codex-swarm/def456

3. codex_wait(task_ids=["abc123", "def456"])
4. git merge codex-swarm/abc123
5. git merge codex-swarm/def456

每个任务都有自己的git工作树和基于HEAD的分支。完成后，将分支合并回去。工作树在24小时后自动清理（可通过以下方式配置 CODEX_SWARM_TASK_MAX_AGE).

实时监控

Call codex_status(task_ids=["abc123"])
-->
=== Task abc123 (45s elapsed) ===
Phase: running
Tools called: 23
Last tool: exec_command(grep -rn "handleError" src/)
Output: Analyzing error handling patterns across the codebase...

会话连续性

1. Call codex(prompt="Review this file")  -->  result + session persisted
2. Call codex_reply(threadId="", prompt="Now fix the bug you found")

服务器标志

每次通话参数

支持Codex MCP官方工具的所有参数：

• prompt （必填）
• model --覆盖服务器默认值
• sandbox -- read-only, workspace-write, danger-full-access
• approval-policy -- untrusted, on-failure, on-request, never
• cwd --工作目录
• profile --配置文件来自 config.toml
• config --键的对象=值覆盖
• worktree --在隔离的git工作树中运行（防止并行任务冲突）
• base-instructions, developer-instructions, compact-prompt

环境变量

需求

• Python 3.8+
• Codex CLI 已安装并验证
• 无pip依赖项（仅限stdlib）
• 适用于Linux和macOS（Linux通过以下方式获得额外的PID重用保护和僵尸检测 /proc)

学分

最初灵感来自 jeanchristophe13v/codex mcp异步。重写了全标志奇偶校验、JSONL状态解析、批处理等待和会话回复支持。

许可证

麻省理工学院