Skip to main content
Glama
Codex Antigravity MCP Server

Codex Antigravity MCP Server

by Vyrmedea

Codex Antigravity MCP Server

"GPT不说人话、不背责任不粘锅而感觉每次对话都像在打卡上班?"
"Gemini满是活人感、但智商不太够导致完全不能用?"

当然是选择让Gemini去拷打gpt了!

轻量级本地MCP服务, 将OpenAI Codex CLI(codex app-server --listen stdio://)桥接封装为Antigravity、Claude Desktop、Cursor等各类 Agent 宿主可直接调用的标准服务.


核心特性

  • 原生历史会话续接与多轮上下文恢复 (threadId):

    • 直接复用 Codex 原生保存在 ~/.codex 的会话持久化存储.

    • 通过 sourceKinds: ["cli", "vscode", "exec", "appServer", "unknown"] 跨越终端 CLI、VS Code 插件以及 MCP, 无缝列出并无损续接历史对话.

    • 支持向宿主 Agent 直接回显指定历史会话的消息摘要与上下文.

  • 工作区目录与沙箱策略精准映射 (effectiveCwd):

    • 自动规范化解析 effectiveCwd (显式传入 -> 恢复会话目录 -> 默认工作区).

    • 将权限档位精确映射为底层 Codex 沙箱策略:

      • supervised (默认推荐): 工作区可写 (writableRoots: [effectiveCwd]), 网络禁用, 敏感操作与终端命令由宿主代理审批 (on-request).

      • full-access: 免审批完全访问 (danger-full-access).

      • read-only: 只读模式, 禁用写权限与网络访问.

  • 截断指数退避长轮询 (10s -> 20s -> 40s, 上限 45s):

    • 任务执行中未决时自动递增等待窗口, 杜绝无效的密集高频空转.

    • 任务执行完成、触发反向审批或进程断线时即刻唤醒返回, 绝不无谓挂起.

  • 反向代理审批闭环 (InteractionBroker + codex_approve):

    • 完整代理并转交 Codex 运行期的各项审批: 终端命令执行、文件变更、权限扩增以及交互提问 (user_input).

    • 实时监听服务端 serverRequest/resolved 通知, 杜绝重复提交或响应已失效审批.

  • 安全防误删可选项 (CODEX_SAFE_TRASH):

    • 防御性拦截直接永久删除命令 (如 rm -rf, del /f, Remove-Item 等), 强制要求使用回收站/垃圾箱参数.

    • 支持通过环境变量 CODEX_SAFE_TRASH=false 全局关闭, 或在 codex_send 中传入 safeTrashOnly: false 进行单次覆盖.

  • 实时状态聚合与命令尾部追踪 (TurnTracker):

    • 内存流式汇聚 Codex 回复文本.

    • 实时维护当前正在运行之终端命令的 4KiB UTF-8 滚动输出尾部 (activeCommand), 方便实时查看构建或测试动态.


Related MCP server: codex-mcp-server

MCP 对外工具契约

工具名称

参数列表

功能说明

codex_send

prompt: 提示词文本cwd?: 工作目录 (省略时自动对齐)threadId?: 历史会话 ID (省略时创建新会话)model?: 指定模型effort?: 推理深度 (low/medium/high)serviceTier?: 速率模式 (default/priority)permissionMode?: "supervised" | "full-access" | "read-only"safeTrashOnly?: 是否强制仅移入垃圾箱 (默认遵循配置)waitMs?: 初始等待毫秒数 (范围 0..45000, 默认 10000)

启动新一轮任务执行. 若存在未结束任务则返回 BUSY. 初始窗口返回快照及下次建议轮询间隔.

codex_poll

threadId: 会话 IDturnId: 轮次 IDcursor?: 事件游标 (默认 0)waitMs?: 自定义等待毫秒数 (省略时按退避表自动等待)

轮询当前运行中任务的最新进展. 任务完成、审批触发或超时后唤醒返回.

codex_approve

threadId: 会话 IDturnId: 轮次 IDinteractionId: 审批请求 ID (从快照中获取)decision: "accept" | "decline" | "cancel"answers?: 交互提问键值对waitMs?: 审批后等待毫秒数 (默认 10000)

回复 Codex 执行期的反向审批请求, 自动根据安全配置拦截危险删除命令.

codex_cancel

threadId: 会话 IDturnId: 轮次 ID

中断正在执行的任务, 发送 turn/interrupt 并等待终态确认.

codex_sessions

cwd?: 按工作区筛选threadId?: 指定会话 IDlimit?: 数量上限 (默认 20)

省略 threadId 时列出所有历史会话; 传入 threadId 时读取该会话的历史对话详情.


环境变量说明

环境变量

默认值

作用说明

CODEX_BIN_PATH

codex

Codex CLI 执行文件路径 (支持系统 PATH 中的 codex, 或 codex.exe / codex.js 的绝对路径).

CODEX_NODE_PATH

node / process.execPath

运行入口为 JS 脚本时所调用的 Node.js 可执行文件路径.

CODEX_DEFAULT_CWD

process.cwd()

当请求与续接会话均未指定目录时的默认回退工作区.

CODEX_SAFE_TRASH

true

是否全局强制启用"仅移动到垃圾箱"安全拦截规则, 设置为 false 可解除限制.


快速上手

1. 前置依赖

2. 安装与构建

git clone https://github.com/<你的用户名>/codex-antigravity-mcp.git
cd codex-antigravity-mcp

# 安装依赖
npm install

# 编译 TypeScript 至 dist/
npm run build

# 运行自动化测试套件 (17 个用例全部通过)
npm test

3. 配置接入示例

Antigravity 配置

在 Antigravity 的 MCP 配置文件中加入:

{
  "mcpServers": {
    "codex": {
      "command": "node",
      "args": [
        "<你的项目绝对路径>/dist/index.js"
      ],
      "env": {
        "CODEX_BIN_PATH": "codex",
        "CODEX_SAFE_TRASH": "true"
      }
    }
  }
}

Claude Desktop 配置

在 claude_desktop_config.json 中配置:

{
  "mcpServers": {
    "codex": {
      "command": "node",
      "args": [
        "<你的项目绝对路径>/dist/index.js"
      ]
    }
  }
}

开发与验证

# 纯类型检查 (不输出文件)
npm run typecheck

# 依据本机安装的 Codex app-server 重新生成 TypeScript 协议类型
npm run protocol:generate

# 运行单元与集成测试 (内置 fake-app-server 双向测试)
npm test

# 运行真实环境两轮长对话冒烟验收
node scripts/smoke.mjs

开源协议

本项目采用 MIT 协议开源.

Available Tools

5 tools
codex_approveA

回复 Codex 的反向审批请求 (命令执行、文件更改、权限申请或用户交互提问). 会自动拦截危险的直接删除命令并转为 decline.

Inputs: turnId (required), decision (required), threadId (required), interactionId (required), +2 more.

codex_cancelA

取消当前运行中的 Codex 执行轮次. 发送中断指令并等待最多 5 秒确认. 在旧命令确认停止前保持忙碌状态以防止并发写冲突.

Inputs: turnId (required), threadId (required).

codex_pollA

轮询当前运行中的 Codex 任务进度. 未传 waitMs 时自动按截断指数退避 (20s -> 40s) 等待. 当任务完成、触发审批或断线时立刻返回.

Inputs: turnId (required), threadId (required), cursor, waitMs.

codex_sendA

向 Codex 发送提示词 (支持新建会话或在已有 threadId 上继续对话). 支持设置工作区目录、模型和权限模式. 在初始窗口 (默认 10s) 内等待, 若未完成则返回快照及下一次轮询的推荐退避时间.

Inputs: prompt (required), cwd, model, effort, +5 more.

codex_sessionsB

查看本地 Codex 原生历史会话列表或指定会话的历史对话详情. 支持覆盖全来源 (CLI / VS Code / 桌面端 / exec / appServer).

Inputs: cwd, limit, threadId.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool maps to a distinct lifecycle operation: send input, poll progress, approve requests, cancel execution, or inspect sessions. The boundaries are clear even though send and poll both involve waiting, because their descriptions explain that send starts/continues work while poll only observes it.

    Naming Consistency4/5

    All tools share a consistent codex_ prefix, and four of five use clear action verbs. codex_sessions is noun-based and combines list/detail behavior, which is a minor deviation from the otherwise consistent verb pattern.

    Tool Count5/5

    Five tools are well-scoped for a Codex execution wrapper, covering the essential lifecycle without redundant endpoints. Each tool earns its place and no obvious duplicate surface exists.

    Completeness4/5

    The set covers sending prompts, continuing threads, polling, approvals, cancellation, and session history, which supports the core workflow. Minor gaps include no explicit session deletion or model/configuration discovery, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP clients to spawn and control Codex CLI and Claude Code sessions on the host machine, with session management and filesystem access.
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Wraps OpenAI Codex CLI as an MCP server, exposing 8 Codex tools (exec, review, skill list, skill run, status, poll, list jobs, kill) as named tools for use with pi or codex.
      1,915 npm
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local stdio MCP server that lets any MCP client start a Codex thread and continue it by opaque thread ID through the codex and codex-reply tools, with fail-closed sandboxing and approval policies. It restores the removed Codex CLI MCP integration by bridging clients like OpenCode to the official Codex SDK.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude Code or any MCP client to delegate hands-on coding work to OpenAI Codex over a persistent app-server process, keeping long-lived threads with follow-ups, async polling, approvals, steering, and interrupts. Supports native code review, resuming existing sessions, structured output, and parallel worktree-isolated tasks.
      10
      34 npm
      1
      MIT