Skip to main content
Glama
sgs844575

image-understand-mcp

by sgs844575
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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 后，就能通过调用工具"看图说话"。

Related MCP server: Vision MCP Server

功能

  • 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 无效、模型名不对，还是配额不足。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers