claude-vision-mcp

基于 Claude API 的视觉识别 MCP server:为不支持视觉识别的主模型多一双眼睛。

这是什么

一个 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。

安装

方式一:uvx(推荐,Claude Code 集成)

无需 clone,直接在 Claude Code 配置里挂载:

// ~/.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。

方式二:本地开发

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

环境变量

网关配置(必填)

超时/重试配置(选填,未设时用默认值)

网关调用默认走流式(SSE),对瞬态错误(超时、连接失败、429 限流、5xx、524)做有限重试,指数退避。以下变量可覆盖默认值,在 .claude.json 的 env 字段透传:

所有变量均从环境读取,非法值(非数字、负数)回退默认值不抛错。

客户端 timeout 配置注意点(重要)

调用方在 .claude.json 的 MCP server 条目里配置的 timeout 字段,是每次工具调用的硬墙钟上限(单位毫秒,超时即中止调用)。视觉识别走流式后,推理重的模型(如 kimi 系)单次调用可能超过 2 分钟。若配置了过小的 timeout(如 120000),长耗时调用会被客户端中止、结果全丢。

建议:

• 不配置 timeout 字段(推荐):回退到 MCP_TOOL_TIMEOUT 默认约 28 小时,实际不限;超过 2 分钟的调用会自动转后台任务,结果不丢。
• 或调大到覆盖模型最坏生成时间(如 600000)。

{
  "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 —— 视觉调用可能超过 2 分钟
    }
  }
}

流式行为说明

• 默认流式:请求体带 stream: true,网关边生成边返回,规避推理重模型非流式生成期的网关读超时(HTTP 524)。
• 兼容回退:网关若忽略 stream 仍回标准 JSON,按非流式结果解析,行为不变。
• 降级兜底:个别不支持流式的模型返回 4xx 时,自动降级为非流式重试一次,保证仍可用(此类模型天生慢,可能因网关读超时失败)。
• 524 重试:524(网关读超时)已纳入重试白名单,偶发的 524 会被 VISION_MAX_RETRIES 重试吸收。

工具

describe_image

识别本地图片并返回文字描述。

参数:

返回: 纯文字描述(tool_result 只含 text block,绝不返回 image block)。

失败处理: 图片读取失败、网关配置缺失、网关调用失败均以文字诊断返回(不抛错),主代理据此向用户反馈或重试。

架构

src/claude_vision_mcp/
├── pure.py     # 纯函数:请求体构造/SSE 解析/响应提取/错误诊断/脱敏/media_type 推断(单测覆盖)
├── gateway.py  # http 调用:httpx 直调 /v1/messages,流式主路径 + JSON 兼容回退(不纳入单测)
├── server.py   # FastMCP stdio 入口:注册 describe_image 工具
└── __init__.py

纪律:

• 纯函数优先:网关请求体构造、响应文字提取为纯函数,单测覆盖;http 调用本身不纳入单测。
• 禁止硬编码端点/模型/密钥:全走环境变量。
• 日志脱敏:server 内部 stderr 日志经 redact_sensitive 脱敏,无密钥/图片 base64 明文泄露。
• MCP stdio 协议:日志走 stderr,stdout 仅供 JSON-RPC。

后续扩展

当前仅 describe_image。后续可在 server.py 增量注册 describe_video / describe_audio 等工具,共用 gateway.py 的网关调用层。包名 claude-vision-mcp 已为多模态预留命名空间。

开发

uv sync --extra dev
uv run pytest            # 测试(纯函数 + gateway 重试路径 + 流式解析,共 90 用例)
uv run ruff check .      # lint
uv run ruff format .     # 格式化
uv run mypy src tests    # 类型检查

发布

打 v* tag 触发 CI 自动发布到公网 PyPI。打 tag 前需更新版本号:

1. 改 pyproject.toml 的 version = "0.x.y"(唯一需改的地方,__init__.py/server.py 运行时从包元数据自动读取)
2. 提交后打 tag:git tag v0.x.y && git push origin v0.x.y

未更新版本号会导致 uv publish 报 409(版本已存在)。

License

MIT