image-understand-mcp

让纯文本模型也拥有图片理解能力的 MCP 服务。

原理

纯文本大模型本身无法处理图片，但可以调用 MCP 工具。本服务作为一个"视觉能力代理"：

纯文本模型（Claude / GPT / 通义千问 等，无视觉能力）
      │  调用 MCP 工具 understand_image(image, prompt)
      ▼
image-understand-mcp（本服务）
      │  读取本地文件 / 下载 URL / 解析 base64 → data URI
      │  转发给你在配置中指定的视觉模型（OpenAI 兼容接口）
      ▼
视觉模型（GPT-4o / Qwen-VL / GLM-4V / Kimi-VL 等）
      │  返回图片的文字描述
      ▼
纯文本模型继续基于文字描述进行推理、回答

你只需要在 MCP 配置里填一个"看得懂图"的模型的 API 信息，任何纯文本模型接入这个 MCP 后，就能通过调用工具"看图说话"。

功能

understand_image：分析一张图片，返回详细文字描述或针对指定问题的回答。
- image 支持三种输入：本地文件路径、HTTP(S) URL、data URI / 裸 base64。
- prompt 可选，自定义想让视觉模型回答的问题（如"提取图中所有文字"）。
- provider 可选，当配置了多个视觉模型时可指定使用哪一个。
list_vision_providers：列出当前配置的所有视觉模型及默认使用的模型。

安装

npm install
npm run build

配置

所有配置通过环境变量传入（在 MCP 客户端的 env 字段中设置）。

方式一：单个视觉模型（最简单）

{
  "mcpServers": {
    "image-understand": {
      "command": "node",
      "args": ["/path/to/image-understand-mcp/dist/index.js"],
      "env": {
        "VISION_BASE_URL": "https://api.openai.com/v1",
        "VISION_API_KEY": "sk-xxxxxxxx",
        "VISION_MODEL": "gpt-4o"
      }
    }
  }
}

适用于任何 OpenAI 兼容协议的视觉模型服务，例如：

服务商	VISION_BASE_URL 示例	VISION_MODEL 示例
OpenAI	`https://api.openai.com/v1`	`gpt-4o`
阿里通义千问	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen-vl-plus`
智谱 AI	`https://open.bigmodel.cn/api/paas/v4`	`glm-4v-flash`
月之暗面 Kimi	`https://api.moonshot.cn/v1`	`moonshot-v1-8k-vision-preview`
硅基流动 SiliconFlow	`https://api.siliconflow.cn/v1`	`Qwen/Qwen2-VL-72B-Instruct`
本地 Ollama	`http://localhost:11434/v1`	`llava`

方式二：配置多个视觉模型，供调用方按需选择

{
  "mcpServers": {
    "image-understand": {
      "command": "node",
      "args": ["/path/to/image-understand-mcp/dist/index.js"],
      "env": {
        "VISION_PROVIDERS": "[{\"name\":\"gpt4o\",\"baseUrl\":\"https://api.openai.com/v1\",\"apiKey\":\"sk-xxx\",\"model\":\"gpt-4o\"},{\"name\":\"qwen-vl\",\"baseUrl\":\"https://dashscope.aliyuncs.com/compatible-mode/v1\",\"apiKey\":\"sk-yyy\",\"model\":\"qwen-vl-plus\"}]",
        "VISION_DEFAULT_PROVIDER": "gpt4o"
      }
    }
  }
}

配置后，纯文本模型调用 understand_image 时可传入 provider: "qwen-vl"来指定使用哪个视觉模型；不指定则使用 VISION_DEFAULT_PROVIDER（缺省为数组中的第一个）。

环境变量说明

变量	必填	说明
`VISION_BASE_URL`	二选一	视觉模型 API 的 base URL（不含 `/chat/completions`）
`VISION_API_KEY`	二选一	API Key
`VISION_MODEL`	二选一	模型名称
`VISION_TIMEOUT_MS`	否	单次请求超时时间（毫秒），默认 60000
`VISION_PROVIDERS`	二选一	JSON 数组，配置多个 provider（见上方示例）
`VISION_DEFAULT_PROVIDER`	否	多 provider 时的默认 provider 名称

VISION_PROVIDERS 与 VISION_BASE_URL/VISION_API_KEY/VISION_MODEL 二选一；若同时设置，优先使用 VISION_PROVIDERS。

本地开发

npm run dev          # 用 tsx 直接运行 src/index.ts
npm run build         # 编译到 dist/
npm run inspector      # 用 MCP Inspector 交互式调试（需先 build）
node scripts/smoke-test.mjs   # 端到端冒烟测试（mock 视觉模型 API，无需真实 API Key）

常见问题

Q: 图片必须是什么格式？A: 支持常见格式（PNG/JPEG/WebP/GIF/BMP），本地路径按扩展名或文件头判断类型，URL 优先用响应头 Content-Type。

Q: 报错 "未找到视觉模型配置"？A: 检查是否正确设置了 VISION_BASE_URL/VISION_API_KEY/VISION_MODEL，或 VISION_PROVIDERS。

Q: 视觉模型返回错误？A: 工具会把视觉模型 API 返回的 HTTP 状态码和错误信息透传给调用方模型，便于定位是 Key 无效、模型名不对，还是配额不足。

image-understand-mcp