内容
# codex-vision-mcp
将 Codex 应用服务器的图片理解功能暴露给 MCP 客户端，作为一个工具：
- `understand_image`
该工具接受一个或多个本地图片路径或 HTTP(S) 图片 URL 和一个自由形式的提问。适用于截图、OCR、错误截图、UI 审查、图表和视觉比较。
## 安装
```powershell
git clone https://github.com/lyd123qw2008/codex-vision-mcp.git
cd codex-vision-mcp
npm run smoke
```
工具参数：
```json
{
"images": ["D:\\tmp\\demo.png"],
"question": "这张图展示了什么？",
"detail": "high"
}
```
## 身份验证
该服务器不需要单独的视觉 API 密钥。它启动本地的 `codex 应用服务器`，并重用此机器上的 Codex CLI 身份验证/配置。
在新机器上，请先进行身份验证：
```powershell
codex login
```
高级覆盖选项：
- `CODEX_JS`： `@openai/codex/bin/codex.js` 的完整路径
- `CODEX_BIN`：启动 Codex 的命令或可执行文件
- `CODEX_VISION_MODEL`：Codex 应用服务器的模型，默认为 `gpt-5.4`
- `CODEX_VISION_WORKDIR`：相对图片路径的基础目录
- `CODEX_VISION_TIMEOUT_MS`：请求超时，默认为 `180000`
- `CODEX_VISION_MAX_IMAGES`：每次调用的最大图片数，默认为 `5`
- `CODEX_VISION_MAX_IMAGE_MB`：本地图片的最大大小，默认为 `20`
## Claude Code 配置
从存储库目录添加此 MCP 服务器：
```powershell
$server = (Resolve-Path .\src\server.js).Path
claude mcp add -s user codex-vision-mcp -- node $server
```
如果相对图片路径应从特定目录解析：
```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
```
等效的用户级配置结构：
```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"
}
}
}
```
示例提示：
```text
请调用 understand_image 分析 D:\tmp\error.png，告诉我这个报错原因和下一步怎么排查。
```
验证 Claude Code 是否能看到该工具：
```powershell
claude mcp list
claude --print "请使用 understand_image 工具分析本地图片 D:\tmp\demo.png，问题是：这张图展示了什么？" --allowedTools "mcp__codex-vision-mcp__understand_image"
```
如果已经打开的 Claude Code 会话没有显示该工具，请在更改 MCP 配置后重启该会话。
当通过 Claude Code 使用诸如 GLM 之类的路由文本模型时，MCP 工具结果可能首先出现在工具输出行下的终端中。Claude Code 仍然需要另一个模型回合将该工具结果转换为最终的助手回复，因此最终回复可能会滞后于工具结果。
## 本地烟雾测试
```powershell
npm run smoke
```
这仅验证 MCP 初始化和工具/列表。实际的图片理解功能由诸如 Claude Code 之类的 MCP 客户端进行。
