Image Vision

English

image-vision-mcp 是一个 MCP Server，用来给 Claude Code 工作流补充图片理解能力。它可以分析本地图片或远程图片 URL，支持多图输入，并通过缓存的 session_id 继续追问。

功能

• 通用图片理解、OCR、UI 分析、错误截图诊断、技术图理解、图表分析和 UI 差异检查。
• 支持本地文件和 HTTP 图片 URL。
• 单次请求支持多张图片。
• 通过 session_id 继续追问。
• 图片 blob 和对话历史分开存储，避免重复写入大体积 base64。
• 日志写入 stderr，可选本地 JSONL 详细调用日志，并自动遮蔽敏感值。

安装要求

• Node.js：运行 release zip 中的 dist/index.js。
• Claude Code CLI：执行 claude mcp add。
• 一个兼容 Anthropic Messages 或 OpenAI chat completions 的多模态 API 端点。
• IMAGE_VISION_AUTH_TOKEN。
• Bun：仅源码开发和打包需要。

安装

从 GitHub Releases 下载 image-vision-mcp-vX.Y.Z.zip，解压到一个长期使用的目录。Release zip 已包含运行所需文件，不需要执行 npm install 或 bun install。

注册到 Claude Code：

claude mcp add -s user image-vision -- node /absolute/path/to/image-vision-mcp/dist/index.js

验证：

claude mcp get image-vision

更详细的跨平台安装、更新和移除步骤见 SKILL.zh-CN.md。

配置

默认用户配置文件路径：

~/.image-vision-mcp/config.json

最小配置：

{
  "api": {
    "provider": "anthropic",
    "authToken": "your-token",
    "baseUrl": "https://your-compatible-endpoint",
    "model": "openai/qwen3.6-plus"
  }
}

OpenAI 兼容视觉端点使用同样的配置结构：

{
  "api": {
    "provider": "openai",
    "authToken": "your-token",
    "baseUrl": "https://example.com/v1",
    "model": "your-vision-model"
  }
}

配置优先级：

非空 config.json 配置 > 环境变量 > 内置默认值

设置 IMAGE_VISION_CONFIG 可以使用自定义配置文件路径。config.json 里的空字符串会被视为未设置，不会覆盖环境变量。

关键环境变量：

变量	必填	默认值	说明
IMAGE_VISION_AUTH_TOKEN	是	无	API token。
IMAGE_VISION_BASE_URL	否	SDK 默认值	上游 API 地址。
IMAGE_VISION_MODEL	否	openai/qwen3.6-plus	图片分析模型。
IMAGE_VISION_CONFIG	否	~/.image-vision-mcp/config.json	自定义配置文件路径。
VISION_API_PROVIDER	否	anthropic	上游 API 格式：anthropic 或 openai。

旧变量仍然兼容：

推荐变量	旧变量
IMAGE_VISION_AUTH_TOKEN	ANTHROPIC_AUTH_TOKEN
IMAGE_VISION_BASE_URL	ANTHROPIC_BASE_URL
IMAGE_VISION_MODEL	QWEN_MODEL
IMAGE_VISION_DIAGNOSTIC_MODEL	ANTHROPIC_MODEL

完整配置结构和全部环境变量见 config.example.json 与 Configuration And Packaging Design。

工具

服务保留 analyze_image 作为兼容入口，同时提供更具体的图片工具：

工具	用途
image_analysis	没有专用工具适配时的通用图片理解。
extract_text_from_screenshot	OCR 截图、代码、终端、文档和 UI 文字。
diagnose_error_screenshot	解释错误截图并建议修复。
understand_technical_diagram	理解架构图、流程图、UML、ER 图和系统图。
analyze_data_visualization	读取图表和仪表盘中的趋势、数值、异常和 caveat。
ui_to_artifact	将 UI 截图转换为代码、提示词、规格或描述。
ui_diff_check	对比两张 UI 截图的视觉或实现差异。
analyze_image	原始通用图片分析工具。

调用规则：

• 将用户提供的原始本地路径或原始图片 URL 作为 source 传入。
• 不要先用宿主 Read 工具读取图片。
• 不要传入临时上传/代理 URL，例如包含 /data-uri/null/ 的路径。
• 后续追问使用 structuredContent.session_id。

详细工具路由规则见 SKILL.zh-CN.md。

示例

首次图片分析：

{
  "source": "C:\\Users\\you\\Pictures\\example.png",
  "prompt": "请详细描述这张图片。"
}

OCR：

{
  "source": "C:\\Users\\you\\Pictures\\terminal-error.png",
  "prompt": "只返回识别出的文字，并保留终端换行。"
}

追问：

{
  "session_id": "img_...",
  "prompt": "右上角有什么文字？"
}

开发

安装依赖：

bun install

常用命令：

bun run test
bun run typecheck
bun run build
bun run build:bundle

创建 release zip：

bun run package

创建或上传 release artifact 之前，先更新根目录 package.json 的 version。Release 打包细节见 Configuration And Packaging Design。

备注

• Release 用户应运行 node dist/index.js；Bun 只用于源码开发。
• 详细调用日志默认写入 ~/.image-vision-mcp/call-logs。
• 缓存数据默认存储在 ~/.image-vision-cache。
• 会话默认 24 小时过期。