Skip to main content
Glama

Codex MCP Server

把本机 Codex CLI 暴露为三个 MCP 工具:支持多附件的对话 codex_chat、画图 codex_draw 和修改图片 codex_edit。默认地址为 http://127.0.0.1:9827/mcp,使用官方 MCP SDK 的无状态 Streamable HTTP(JSON 响应)。

安装 skill / 接入已有服务

其他 AI Agent 安装本项目 skill 时,不安装 Codex CLI、不执行 Codex 登录、不启动服务。将 skills/codex-mcp-server 整个目录(含脚本)复制到 Agent 的技能目录即可。客户端只连接已运行的 MCP 服务;Codex CLI 和账号由服务端维护。

使用已有 Node.js 22+ 检测服务,无需 npm install:

node skills/codex-mcp-server/scripts/check-service.mjs
# 自定义服务端口
node skills/codex-mcp-server/scripts/check-service.mjs --url http://127.0.0.1:9828/mcp
# 额外验证图片生成能力
node skills/codex-mcp-server/scripts/check-service.mjs --draw

检测包含 HTTP 端口和 /health、MCP 初始化与工具发现,以及一次真实 codex_chat 调用。默认不生成图片;--draw 会额外调用 codex_draw 并检查 PNG 内容。真实调用使用服务端账号,可能产生用量。成功退出码为 0,失败为 1 并输出失败阶段;服务未启动、协议不匹配或后端不可用时报告问题,不自动安装或修复服务端。协议请求默认 10 秒、工具调用默认 660 秒,可通过 --timeout-ms / --tool-timeout-ms 调整。

Related MCP server: local_vision

服务端部署(仅服务维护者)

以下步骤只用于用户主动部署服务端,不是 skill 的安装步骤。

需要 Node.js 22+、已安装并登录的 Codex CLI。画图还需要当前 Codex CLI / 账号具备图片生成能力及可用的 imagegen 技能。先在同一系统用户下确认 Codex 可以正常对话和生成图片。

npm install -g @openai/codex
codex login
npm ci
npm start

Windows PowerShell 可使用 npm.cmd、codex.cmd。服务支持 npm 安装的 Windows Codex 启动器,会解析到其 JavaScript 入口并直接调用 Node,避免通过 shell 执行请求文本。

健康检查:GET http://127.0.0.1:9827/health。此接口仅表示服务正在运行,不验证 Codex 登录状态。

连接 AI Agent

在支持 Streamable HTTP 的 MCP 客户端中添加:

{
  "mcpServers": {
    "codex-local": {
      "url": "http://127.0.0.1:9827/mcp"
    }
  }
}

不同客户端配置格式可能不同,请将传输类型设为 HTTP / Streamable HTTP。该服务不提供旧版 /sse 传输,也不使用 stdio。

使用本项目依赖的 JavaScript SDK:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(
  new URL('http://127.0.0.1:9827/mcp'),
));
try {
  console.log(await client.callTool({
    name: 'codex_chat',
    arguments: { prompt: '用中文解释什么是 MCP' },
  }, undefined, { timeout: 660_000 }));
  console.log(await client.callTool({
    name: 'codex_draw',
    arguments: { prompt: '画一只在月球上喝茶的猫,水彩风格' },
  }, undefined, { timeout: 660_000 }));
} finally {
  await client.close();
}

三个工具均接受必填 prompt(1–100,000 字符)和可选 model(Codex 模型名称,省略时使用 CLI 配置)。每次调用都是独立的 Codex 执行;多轮聊天请在 prompt 中带上需要的历史上下文,并重新上传本轮需要的附件。

  • codex_chat:通过 stdin 传递提示词,可选 attachments 上传多个附件,以 codex exec 执行,返回最终回复的 MCP text 内容。

  • codex_draw:提示 Codex 使用 $imagegen 生成一张图片,并保存到独立任务目录的 output.png。返回 PNG 的 MCP image 内容(base64)以及本机文件路径,调用方无需访问服务器文件系统即可显示图片。

  • codex_edit:必填 images 上传一张或多张参考图片,在 prompt 中描述修改要求。提示 Codex 使用 $imagegen 基于这些图片修改,返回一张 PNG 的 MCP image 内容(base64)及服务端保存路径,与 codex_draw 返回结构一致。

画图和改图读取实际 PNG 文件,不把 CLI 返回的文字当作图片。CLI 不支持生图/改图、账号无权限、未输出图片、文件格式错误或图片超过 10 MiB 时返回 isError: true,并附带错误说明。服务不直接调用 Images API;图片能力和费用取决于本机 Codex 配置。

上传附件与修改图片

attachments 和 images 中每个对象均包含 name(不含目录的原始文件名)、mimeType 和 data(文件字节的标准 base64,含必要的 = 填充,不带 data: 前缀)。调用方读取本地文件后上传内容,不传服务端文件路径或 URL。每次最多 10 个文件,单文件解码后最多 10 MiB,合计最多 20 MiB;改图至少需要 1 张图片。

图片支持 PNG(image/png)、JPEG(image/jpeg)、WebP(image/webp),会校验文件头与 MIME 类型。普通对话还可上传文本、CSV、PDF 等其他文件;服务将原始字节保存到任务目录,具体读取能力取决于服务端 Codex 可用的工具。图片通过 CLI --image 参数传入,其他文件通过提示词中的文件清单读取。

以下代码在上面的 SDK client 已连接时使用:

import { readFile } from 'node:fs/promises';

async function upload(file, name, mimeType) {
  return { name, mimeType, data: (await readFile(file)).toString('base64') };
}

const photo = await upload('./photo.jpg', 'photo.jpg', 'image/jpeg');
const reference = await upload('./reference.png', 'reference.png', 'image/png');
console.log(await client.callTool({
  name: 'codex_edit',
  arguments: {
    prompt: '把第一张照片的背景换成第二张图中的花园,保留人物外貌和衣服。',
    images: [photo, reference],
  },
}, undefined, { timeout: 660_000 }));

console.log(await client.callTool({
  name: 'codex_chat',
  arguments: {
    prompt: '根据需求文档和照片,给出布置建议。',
    attachments: [await upload('./requirements.txt', 'requirements.txt', 'text/plain'), photo],
  },
}, undefined, { timeout: 660_000 }));

附件按传入顺序保存为 attachments/1.jpg 等服务端生成的文件名,同名附件不会相互覆盖。原文件名和 MIME 类型保留在提示词清单中。无效 base64、超限、非法文件名或不匹配的图片类型会返回 isError: true,且不会启动 CLI;整个 HTTP JSON 请求超过 30 MiB 时返回 HTTP 413。

配置

通过环境变量配置(服务不会自动加载 .env):

变量

默认值

说明

PORT

9827

HTTP 端口,1–65535

CODEX_BIN

codex

CLI 命令或可执行文件 / JS 入口路径;不支持拼接额外命令参数

CODEX_TIMEOUT_MS

600000

每次 CLI 执行的超时毫秒数

CODEX_MAX_CONCURRENT

2

同时运行的 CLI 数量,1–32;超出时立即返回 busy 错误,可稍后重试

LOG_FILE

logs/requests.jsonl

JSONL 日志路径

DATA_DIR

data/requests

各任务的输出目录

相对路径以启动服务时的目录为基准。示例(PowerShell):

$env:PORT = '9827'
$env:CODEX_TIMEOUT_MS = '900000'
npm.cmd start

客户端超时也应适当调大,尤其是生成图片时。HTTP 连接中断、服务退出或 CLI 超时会尝试终止对应进程树;Ctrl+C 可停止服务。由于采用无状态传输,跨 HTTP 请求的 MCP notifications/cancelled 不关联到先前请求;请关闭原调用的 HTTP 连接以取消执行。

日志与执行范围

每个收到的 MCP JSON 请求(包括无效工具名和参数)都会带上唯一 requestId,原样打印到 console 并追加到 JSONL 文件。执行命令、任务目录、完成耗时及执行错误使用同一 ID 关联。日志包含完整提示词和上传附件的 base64;请按本机数据保留要求管理。日志、上传附件和输出文件均已加入 .gitignore,不会自动清理或轮转。

服务仅绑定 127.0.0.1,检查 Host / Origin,供同机可信 Agent 使用。没有远程认证功能,请勿直接转发到公网。它继承当前用户的 Codex 登录信息、技能及配置;不要在子 Codex 配置中再次启用本服务,以免递归调用。

所有调用在独立任务目录运行,禁用交互式审批;对话工具使用 read-only 沙箱,画图和改图使用 workspace-write。提示词通过 stdin 传递,子进程使用参数数组和 shell: false。服务不允许调用方指定工作目录、额外 CLI 参数或解除沙箱。HTTP 请求体限制为 30 MiB(为最多 20 MiB 附件的 base64 编码及 JSON 留出空间),CLI stdout/stderr 合计和最终文字各限制为 2 MiB。

测试

npm test

使用 Node 内置测试框架、真实 HTTP MCP 客户端和独立 CLI fixture 进程,不需要登录、API key 或付费模型调用。覆盖工具发现、文字与图片返回、单图/多图修改、多附件字节传递与隔离、文件名/base64/格式/大小校验、双通道日志、CLI 启动失败/非零退出/超时/取消/输出上限、并发限制和 Windows 启动器解析。fixture 测试验证协议及集成路径,不验证实际账号的模型或图片生成/修改可用性。

skill 检测脚本的测试还覆盖无客户端 CLI 的独立运行、自定义端口、协议协商、健康检查/协议/工具调用失败、超时、默认只验证文字及显式图片验证。

参考:Codex 非交互执行、图片生成、MCP SDK Streamable HTTP。

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables ChatGPT to execute Codex CLI prompts locally through a secure MCP tool, with support for both local stdio and remote HTTP modes.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible coding agents to execute the local Codex CLI as a coding agent, including code reviews, session resume/fork, and CLI diagnostics.
      9
      11 npm
      MIT