vision-mcp

给纯文本模型（如 DeepSeek）补上"看图"能力的 MCP 服务器 | Vision MCP server: image recognition for text-only models (DeepSeek, etc.)

English | 中文

这是什么 / What

vision-mcp 是一个标准的 MCP 服务器：通过 MCP 工具为不支持图片输入的大模型（如 deepseek-v4-flash）提供图像识别能力。

不依赖任何特定客户端——Codex、Claude Code、Cursor、Cline、opencode 等任何支持 MCP 的 agent 都能用，别人不需要安装 opencode。

• 默认后端：OpenCode Zen MiMo V2.5 Free（mimo-v2.5-free）——免费、无需 API key，识别质量好。
• 可选后端：本地 Ollama（qwen2.5vl-vision）——离线/隐私场景，图片不出本机。
• 可选：任何 Zen 模型列表里的模型（如 gpt-5.6-luna、qwen3.6-plus），直接传裸模型名即可。

工具 / Tools

工具	说明
vision_recognize	识别/描述图片（内容、文字、颜色、布局、物体位置）。输入支持：本地路径、http(s) URL、file:// URL、data: URI。
vision_grounding	用本地 Ollama 分析 UI 截图，输出交互元素及归一化坐标（0–1000，多轮投票合并）。用于 GUI 自动化。
vision_status	健康检查：Zen 可达性 + Ollama 可达性，列出可用模型。

安装运行 / Install & run

npm install -g vision-mcp    # 或本地：npm run build && node dist/index.js
vision-mcp                   # 启动 stdio MCP 服务器
vision-mcp doctor            # 诊断报告（后端可达性/模型列表）

或者不安装直接用：

npx -y vision-mcp

要求 Node.js 18+。

客户端配置 / Client configuration

Codex（~/.codex/config.toml）：

[mcp_servers.vision]
command = "npx"
args = ["-y", "vision-mcp"]

Claude Code：

claude mcp add vision -- npx -y vision-mcp

opencode（opencode.json）：

{
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["npx", "-y", "vision-mcp"],
      "enabled": true
    }
  }
}

Cursor：设置 → MCP → 添加 → 命令：npx -y vision-mcp

使用 / Usage

直接让你的 agent "看一下 / 描述 / 读一下这张图"，把路径或 URL 给它：

描述 C:\path\to\image.png —— 图里有什么文字和物体？

agent 会自动调用 vision_recognize。GUI 自动化场景：vision_grounding —— "列出 screenshot.png 里的按钮及其位置"。

配置（环境变量）/ Configuration

变量	默认值	说明
ZEN_BASE	https://opencode.ai/zen	OpenCode Zen 端点
ZEN_MODEL	mimo-v2.5-free	默认 Zen 模型（免费）
ZEN_API_KEY / OPENCODE_ZEN_API_KEY	—	可选，使用付费 Zen 模型时需要
OLLAMA_BASE	http://127.0.0.1:11434	本地 Ollama 端点
OLLAMA_MODEL	qwen2.5vl-vision	本地 Ollama 视觉模型
VISION_TIMEOUT_MS	180000	单次请求超时
GROUNDING_ROUNDS	3	grounding 投票轮数

vision_recognize 传 model: "local" 强制走本地 Ollama；否则默认用 Zen 模型。任意裸模型名（如 gpt-5.6-luna）会直接透传给 Zen。

隐私说明 / Privacy

默认免费模型 mimo-v2.5-free 为尽力提供，可能随时变更；免费期间数据可能用于改进模型。敏感图片请配置 API key 或使用 model: "local" 全本地处理。

开发 / Development

npm install
npm run build        # tsc -> dist/
node scripts/smoke-test.mjs   # 端到端 MCP 客户端冒烟测试（需联网，可选 Ollama）
npm run doctor       # 同 node dist/index.js doctor

许可证 / License

MIT