# 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

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

Tool arguments:

```json
{
  "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:

```powershell
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:

```powershell
$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:

```powershell
$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:

```json
{
  "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:

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

Verify Claude Code can see the tool:

```powershell
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

```powershell
npm run smoke
```

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