claude-vision-mcp

# claude-vision-mcp > 基于 Claude API 的视觉识别 MCP server:为不支持视觉识别的主模型多一双眼睛。 [](https://pypi.org/project/claude-vision-mcp/) ## 这是什么 一个 stdio MCP server,暴露 `describe_image` 工具。主代理(如 Claude Code)调用它传入本地图片路径,工具内部用 http 直调视觉网关的 `/v1/messages`,**把图片放在 user message 顶层 image content block**(绕开网关只解析顶层 image、不解析 `tool_result` 内嵌 image 的兼容缺陷),视觉模型返回的文字作为 `tool_result` 返回给主代理。 **为什么需要它**:Claude Code 的 `Read` 工具读图时,会把图片塞进 `tool_result.content` 内嵌的 image block。但部分网关(如本环境的 `xopkimik26`)只解析 user message **顶层** image、不解析 `tool_result` 内嵌 image——结果主模型「看不到图」。本工具把识图挪到一个独立的 MCP server 里,**对主代理消息流可见的永远是纯文字 tool_result**,图片在工具内部的 http 调用中消化,从源头绕开缺陷。 详细背景见 [cnpc/claude #48](https://cnb.cool/cnpc/claude/-/issues/48)。 ## 安装 ### 方式一:`uvx`(推荐,Claude Code 集成) 无需 clone,直接在 Claude Code 配置里挂载: ```jsonc // ~/.claude.json 或项目 .claude.json { "mcpServers": { "claude-vision-mcp": { "command": "uvx", "args": ["claude-vision-mcp"], "env": { "ANTHROPIC_BASE_URL": "${ANTHROPIC_BASE_URL}", "ANTHROPIC_AUTH_TOKEN": "${ANTHROPIC_AUTH_TOKEN}", "VISION_MODEL": "${VISION_MODEL}" }, "timeout": 120000 } } } ``` `uvx` 会自动从 PyPI 拉起最新版本,隔离虚拟环境,不污染系统 Python。 ### 方式二:本地开发 ```bash git clone https://cnb.cool/cnpc/mcp/claude-vision-mcp.git cd claude-vision-mcp uv sync --extra dev # 装依赖 + dev 依赖 uv run pytest # 跑测试 uv run python -m claude_vision_mcp.server # 直接启动 stdio server ``` ## 环境变量 ### 网关配置(必填) | 变量 | 必填 | 说明 | | --- | --- | --- | | `ANTHROPIC_BASE_URL` | 是 | 视觉网关基地址(如 `https://api.cnb.cool/...`),不带尾部斜杠 | | `ANTHROPIC_AUTH_TOKEN` | 是 | 网关认证令牌,同时用作 `x-api-key` 与 `Authorization: Bearer` | | `VISION_MODEL` | 是 | 支持视觉的多模态模型 ID(如 `xopkimik26`),由调用方注入不写死 | ### 超时/重试配置(选填,未设时用默认值) 网关调用**默认走流式**(SSE),对瞬态错误(超时、连接失败、429 限流、5xx、524)做有限重试,指数退避。以下变量可覆盖默认值,在 `.claude.json` 的 `env` 字段透传: | 变量 | 默认值 | 说明 | | --- | --- | --- | | `VISION_CONNECT_TIMEOUT` | `10` | TCP …