vision-mcp

为纯文本主模型补齐视觉能力的轻量 MCP server。当主模型遇到图片（截图、UI 图、流程图、报错截图等）但无法理解时，通过 MCP 工具把图片交给 OpenAI 兼容的多模态后端（Qwen-VL、GPT-4o、Gemini、本地 vLLM 等）分析，返回文本结果。

主模型(纯文本) ──调用 MCP 工具──▶ vision-mcp ──Chat Completions──▶ 多模态模型
   Claude/Codex ◀──────文本结果───────◀──────────────────────────   Qwen-VL / GPT-4o / ...

快速开始

推荐：用随仓库分发的 bin/wrapper.sh 直接启动。wrapper 首次调用会自动在目录下创建 .venv 并安装依赖（uv 优先，无 uv 则 venv+pip），无需手动安装；之后 exec 真正的 server.py。适用于 macOS / Linux。

# 方式一（推荐，免手动装依赖）：MCP client 指向 wrapper 即可
claude mcp add vision-mcp -- /绝对/路径/vision-mcp/bin/wrapper.sh

# 或先自测：wrapper 会自举依赖并启动 server
/绝对/路径/vision-mcp/bin/wrapper.sh --check

Windows 请用 python -m venv + install.ps1，或直接 python server.py。

安装（源码自建）

先安装 MCP server 本体（Python）：

# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1
# macOS / Linux
./install.sh

然后按你的客户端接入：

Claude Code

claude mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

Codex

codex mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

修改 MCP 配置后需重启客户端生效。

pi

cp pi-extensions/vision-mcp.ts ~/.pi/agent/extensions/
# 依赖：typebox（必需，工具参数模式定义）；sharp（可选，图片缩放，未装则自动降级为不缩放）
cd ~/.pi/agent/extensions && npm i sharp typebox

复制后重启 pi 或 /reload 自动加载，无需 pi install。pi 扩展支持能力门控：当主模型原生支持图片（input 含 image）时自动隐藏三个视觉工具避免多余委派，纯文本主模型才显示。

配置

优先级：config.json > 进程环境变量 > .env > 默认值。config.json 已被 gitignore，不入库。

cp config.example.json config.json   # 再编辑 api_key 等字段

{
  "api": "openai-completions",
  "api_key": "sk-your-dashscope-api-key",
  "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "model": "qwen-vl-plus",
  "max_tokens": 4096,
  "timeout": 120,
  "max_retries": 2,
  "retry_backoff": 2
}

pi 扩展额外读取 ~/.pi/vision-mcp/config.json（或用 VISION_CONFIG_PATH 指定），键与上述一致。

环境变量	默认值	说明
`VISION_API`	`openai-completions`	后端 API 协议：`openai-completions`（OpenAI Chat Completions）/ `openai-responses`（OpenAI Responses API）/ `anthropic-messages`(Anthropic Messages API)；后两者需 base_url 指向对应端点
`VISION_API_KEY`	-	视觉后端 API Key
`VISION_BASE_URL`	dashscope	OpenAI 兼容端点
`VISION_MODEL`	`qwen-vl-plus`	视觉模型名
`VISION_MAX_TOKENS`	`4096`	单次最大输出 token
`VISION_TIMEOUT`	`120`	请求超时（秒）
`VISION_MAX_RETRIES`	`2`	瞬时故障重试次数
`VISION_RETRY_BACKOFF`	`2`	重试退避基数（秒）
`VISION_MAX_IMAGE_BYTES`	`20971520`	单图大小上限（字节）
`VISION_MAX_IMAGE_DIMENSION`	`4000`	图片最大边长 px，超限等比缩小
`VISION_AUTO_RESIZE`	`true`	是否自动缩放图片
`VISION_CACHE_ENABLED`	`true`	是否启用内存缓存（相同图片+提示在 LRU 窗口内复用，省视觉 API 调用）
`VISION_CACHE_MAX_ENTRIES`	`256`	缓存最大条目数

支持格式：PNG / JPEG / WebP / GIF（BMP 因主流视觉后端不支持而被排除）。

常见后端：DashScope（默认）VISION_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1；OpenAI model=gpt-4o；本地 vLLM base_url=http://localhost:8000/v1。

检查配置

# wrapper 方式（依赖未装则先自举）
./bin/wrapper.sh --check
# 源码自建（依赖手动安装后）
python server.py --check   # 打印生效配置，API key 脱敏

工具

vision_analyze — 通用图片理解。参数：prompt（可选）、image/image_path/image_url/image_base64（四选一）。
vision_ocr — 逐字提取图片文字。参数同 analyze（无 prompt）。
vision_analyze_batch — 批量分析多张。参数：items（必填，每项为四选一图片来源，可带 prompt）、prompt（可选）、concurrency（默认 3，范围 1-8）。

开源

以源码形式开源，欢迎 Fork / Issue / PR。