codex-vision-mcp

Expose Codex app-server image understanding to MCP clients as one tool:

• understand_image

The tool accepts one or more local image paths or HTTP(S) image URLs and a free-form question. It is intended for screenshots, OCR, error screenshots, UI review, diagrams, charts, and visual comparison.

Install

git clone https://github.com/lyd123qw2008/codex-vision-mcp.git
cd codex-vision-mcp
npm run smoke

Tool arguments:

{
  "images": ["D:\\tmp\\demo.png"],
  "question": "这张图展示了什么？",
  "detail": "high"
}

Authentication

This server does not need a separate vision API key. It starts the local codex app-server and reuses the Codex CLI authentication/configuration on this machine.

On a new machine, authenticate Codex first:

codex login

Advanced overrides:

• CODEX_JS: full path to @openai/codex/bin/codex.js
• CODEX_BIN: command or executable to start Codex
• CODEX_VISION_MODEL: model for Codex app-server, default gpt-5.4
• CODEX_VISION_WORKDIR: base directory for relative image paths
• CODEX_VISION_TIMEOUT_MS: request timeout, default 180000
• CODEX_VISION_MAX_IMAGES: max images per call, default 5
• CODEX_VISION_MAX_IMAGE_MB: max local image size, default 20

Claude Code configuration

Add this MCP server from the repository directory:

$server = (Resolve-Path .\src\server.js).Path
claude mcp add -s user codex-vision-mcp -- node $server

If relative image paths should resolve from a specific directory:

$server = (Resolve-Path .\src\server.js).Path
$workspace = "C:\path\to\workspace"
claude mcp add -s user codex-vision-mcp --env CODEX_VISION_WORKDIR=$workspace -- node $server

Equivalent user-level configuration shape:

{
  "codex-vision-mcp": {
    "type": "stdio",
    "command": "node",
    "args": ["C:\\path\\to\\codex-vision-mcp\\src\\server.js"],
    "env": {
      "CODEX_VISION_WORKDIR": "C:\\path\\to\\workspace",
      "CODEX_VISION_MODEL": "gpt-5.4"
    }
  }
}

Example prompt:

请调用 understand_image 分析 D:\tmp\error.png，告诉我这个报错原因和下一步怎么排查。

Verify Claude Code can see the tool:

claude mcp list
claude --print "请使用 understand_image 工具分析本地图片 D:\tmp\demo.png，问题是：这张图展示了什么？" --allowedTools "mcp__codex-vision-mcp__understand_image"

If an already-open Claude Code session does not show the tool, restart that session after changing MCP configuration.

When using a routed text model such as GLM through Claude Code, the MCP tool result may appear first in the terminal under the tool output line. Claude Code still needs one more model turn to convert that tool result into the final assistant reply, so the final reply can lag behind the tool result.

Local smoke test

npm run smoke

This only validates MCP initialize and tools/list. Real image understanding is exercised from an MCP client such as Claude Code.