Vision MCP
基于 VLM 的视觉问答 MCP 服务。通过 OpenAI 兼容 API 调用视觉大模型，提供视觉问答、解读、检测、OCR 能力，以及一组程序化图像处理工具。
特性
- 视觉 QA：基于图像可见内容回答问题，不脑补
- 视觉解读：详细、客观地描述图像，区分事实与推断
- 视觉检测：定位目标并返回 0-1 归一化包围盒
- 视觉 OCR：提取图像文字，照原文不纠正
- 图像辅助工具：元信息、缩放、裁剪、旋转/镜像、拼接、标注（支持中文）
整体原则：忠实还原图像内容，不脑补。
安装
uv sync
配置
复制 .env.example 为 .env 并填写：
VLM_BASE_URL=https://api.openai.com/v1
VLM_API_KEY=sk-xxx
VLM_MODEL_ID=gpt-4o
| 环境变量 | 必需 | 默认 | 说明 |
|---|---|---|---|
VLM_BASE_URL |
是 | - | OpenAI 兼容 API base URL |
VLM_API_KEY |
是 | - | API key |
VLM_MODEL_ID |
是 | - | 视觉模型 ID |
VLM_TIMEOUT |
否 | 60 | 请求超时秒 |
VLM_DETAIL |
否 | high | vision detail：auto/low/high |
VLM_MAX_PIXELS |
否 | 2048 | 送 VLM 前单边像素上限 |
VLM_AUTO_PREPROCESS |
否 | true | 是否自动缩放过大图 |
MCP_HOST |
否 | 0.0.0.0 | 服务监听地址 |
MCP_PORT |
否 | 8000 | 服务端口 |
MCP_TRANSPORT |
否 | http | 传输方式：stdio（本地）/ http（远程） |
MCP_API_KEYS |
否 | - | API key 列表（逗号分隔），启用 Bearer 认证；留空不认证 |
ANNOTATE_FONT_PATH |
否 | - | 中文字体路径，默认用项目自带 fonts/SimHei.ttf，再回退系统字体 |
VLM_OPENAI_LLM_EXTRA_BODY |
否 | - | 透传给 API 的 extra_body（JSON 字符串），如 {"thinking":{"type":"disabled"}} |
启动
通过 MCP_TRANSPORT 环境变量选择传输方式：
# HTTP（远程，默认）—— 端点 http://<host>:<port>/mcp
uv run python -m vision_mcp
# stdio（本地，如作为 Claude Desktop / Cursor 子进程）
MCP_TRANSPORT=stdio uv run python -m vision_mcp
HTTP 模式可通过 MCP_API_KEYS 启用 Bearer 认证；stdio 模式无需认证（本地）。
工具列表
VLM 工具
| 工具 | 说明 |
|---|---|
vision_qa |
视觉问答 |
vision_describe |
视觉解读（concise/normal/detailed） |
vision_detect |
视觉检测，返回归一化包围盒 |
vision_ocr |
视觉 OCR |
图像辅助工具
| 工具 | 说明 |
|---|---|
vision_get_image_info |
图像元信息 |
vision_resize_image |
缩放（宽度/高度/最长边） |
vision_crop_image |
裁剪（归一化或像素坐标） |
vision_transform_image |
旋转与镜像 |
vision_compose_images |
拼接（横向/纵向/网格） |
vision_annotate_image |
标注方框与文本 |
所有图像工具的图像输入统一为 ImageInput，支持 path（本地路径）/ base64 / url 三选一。
架构
src/vision_mcp/
├── server.py # FastMCP 实例 + 注册工具 + 启动
├── config.py # 环境变量配置（pydantic-settings）
├── schemas.py # 数据模型（ImageInput/BBox/Detection 等）
├── vlm/
│ ├── client.py # AsyncOpenAI 封装 + JSON 解析
│ └── prompts.py # 四场景 system prompt
├── image/
│ ├── io.py # 统一加载（path/base64/url）+ EXIF 校正
│ ├── meta.py # 元信息
│ ├── resize.py # 缩放
│ ├── crop.py # 裁剪
│ ├── transform.py # 旋转/镜像
│ ├── compose.py # 拼接
│ └── annotate.py # 标注（中文字体回退）
└── tools/
├── vision.py # 4 个 VLM 工具实现
└── image_ops.py # 图像辅助工具实现
测试
uv run pytest
客户端配置示例
Claude Desktop / Cursor 等 MCP 客户端配置（streamable-http）：
{
"mcpServers": {
"vision-mcp": {
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}
}
}
启用认证（设置了
MCP_API_KEYS）时，客户端必须在请求头携带Authorization: Bearer <key>，且 key 在配置列表中，否则返回 401。
注意事项
- 检测精度：VLM 输出的包围盒精度有限，小目标尤甚。建议先
crop_image局部放大再vision_detect。 - token 成本：
VLM_MAX_PIXELS+VLM_AUTO_PREPROCESS是成本护栏，过大图会自动缩放后送模型。 - HTTP 认证：设置
MCP_API_KEYS后启用 Bearer 认证（支持多 key）；未设置时不认证，仅适合本地/内网。 - 中文字体：默认使用项目自带
fonts/SimHei.ttf，无需额外配置；也可通过ANNOTATE_FONT_PATH指定其他字体。
