内容
# Codex Vision MCP
Codex Vision MCP 是一个本地的MCP服务器，为不支持原生图像输入的编码代理和模型添加计算机视觉工具。它使用现有的Codex OAuth凭证，并调用ChatGPT/Codex响应后端。
主要使用场景是在运行强大的文本/代码模型（如GLM 5.2）的同时，为代理提供一种通过MCP工具检查截图、图表、UI模型、图表图像和本地文件图像的方法。
## 名称
使用 **Codex Vision MCP**。
`Vision MCP` 太过通用。重要的区别在于，该服务器使用Codex OAuth和Codex响应后端作为视觉提供商。
软件包和可执行文件名称为：
- 软件包：`codex-vision-mcp`
- 命令：`codex-vision-mcp`
- 建议的MCP服务器名称：`codex-vision`
## 工具
- `ui_to_artifact`
- `extract_text_from_screenshot`
- `diagnose_error_screenshot`
- `understand_technical_diagram`
- `analyze_data_visualization`
- `ui_diff_check`
- `analyze_image`
- `analyze_video`
工具名称故意与Z.AI视觉MCP工具形状兼容，以便提示和代理行为可以轻松转移。
## 工作原理
MCP客户端调用其中一个视觉工具，带有本地文件路径、远程URL或`data:image/...` URL。该服务器加载图像，将其发送到Codex响应后端，并使用Codex OAuth，然后将文本结果返回给调用代理。
这在活动模型仅为文本时或模型提供商拒绝原生图像输入时很有用。
## 当前限制
在Claude Code中，直接粘贴图像到客户端不会自动调用此MCP服务器。Claude Code转码粘贴的图像并直接将其发送到选定的模型。如果选定的模型不支持图像输入，模型调用可能会在涉及MCP工具之前失败。
目前，请使用本地文件路径并要求代理检查该文件：
```text
./demo.png 描述了什么？
```
或：
```text
使用 codex-vision 分析 /absolute/path/to/demo.png
```
未来的Claude Code集成可以在模型调用之前拦截粘贴的图像，将它们路由到此MCP服务器，然后继续使用纯文本提示。
## 从源代码安装
```bash
npm install
npm run build
node dist/index.js --smoke
```
`--smoke` 检查Codex OAuth发现并打印编辑后的身份验证元数据。
## 添加到Claude Code
建议项目本地注册。它仅为需要它的仓库启用此视觉服务器。
```bash
cd /path/to/your/project
claude mcp add --scope local codex-vision -- npx -y codex-vision-mcp
```
在本地开发：
```bash
cd /path/to/your/project
claude mcp add --scope local codex-vision -- node /absolute/path/to/vision_mcp/dist/index.js
```
在Windows PowerShell上：
```powershell
cd C:\path\to\your\project
claude mcp add --scope local codex-vision -- npx -y codex-vision-mcp
```
## 身份验证
当前的身份验证发现优先使用本地Codex身份验证，然后是明确的环境覆盖：
1. `CODEX_VISION_AUTH_JSON`
2. `CODEX_IMAGEN_AUTH_JSON`
3. `CODEX_AUTH_JSON`
4. `CODEX_HOME/auth.json`
5. `~/.codex/auth.json`
服务器通过`https://auth.openai.com/oauth/token`刷新接近过期的OAuth令牌，并将它们原子化地写回。
## 环境
- `CODEX_VISION_MODEL`: 响应模型，默认为 `gpt-5.5`
- `CODEX_VISION_BASE_URL`: 默认 `https://chatgpt.com/backend-api/codex`
- `CODEX_VISION_AUTH_JSON`: 显式身份验证JSON路径
- `CODEX_VISION_IMAGE_DETAIL`: `auto`, `low`, `high`, 或 `original`
- `CODEX_VISION_TIMEOUT_MS`: 默认 `300000`
- `CODEX_VISION_MAX_IMAGE_MB`: 默认 `10`
- `CODEX_VISION_MAX_VIDEO_MB`: 默认 `50`
- `CODEX_VISION_VIDEO_FRAMES`: 默认 `4`
- `CODEX_VISION_MCP_LOG_PATH`: 可选日志文件路径
## 平台支持
服务器使用Node.js实现，应该可以在macOS、Linux和Windows上运行，Node.js版本为22或更高。
跨平台注意事项：
- 使用Node `path`和`os.homedir()`解析本地路径。
- `~/.codex/auth.json`映射到每个操作系统上的当前用户的主目录。
- 身份验证文件权限在非Windows系统上使用`chmod`收紧。
- 可选的Codex CLI版本查找在`codex`不在`PATH`时安全回退。
- `analyze_video`需要`ffmpeg`在`PATH`上；请在每个操作系统上单独安装`ffmpeg`，或手动提取帧并使用`analyze_image`。
## 开发
```bash
npm run check
npm run build
```
直接运行服务器：
```bash
node dist/index.js
```
