vision-mcp

极简视觉 MCP server：让纯文本模型通过云端视觉模型"看图"。

所有工具都只返回文字——图片在云端视觉模型处理，模型侧永远只收到文本。 因此对不支持图像输入的模型（如 deepseek-v4-flash）100% 可用，也兼容任何支持视觉的模型。

工具

工具	作用
vision_chat(images|videos, text, ...)	看图问答 / 描述（核心）；支持视频自动抽帧
ocr(images, ...)	图片文字识别（原样返回）
grounding(images, ...)	目标定位：返回 [{"label","bbox_2d":[x1,y1,x2,y2]}]（0-1000 归一化坐标）
media_info(path)	ffprobe 探测视频/音频元数据（时长/分辨率/fps/编码/音轨）
clear_memory()	清空当前会话的视觉问答记忆

内置机制

1. 指数退避重试 — 429/5xx/网络错误自动等待后重试（免费 GLM 限流常态，稳定性关键）； 主选模型（4.6 Flash）只重试 1~2 次，仍失败立即切兜底模型，避免反复撞限流拖长耗时
2. GLM 免费家族自动兜底 — glm-4.6v-flash 限流/超时 → glm-4v-flash（全程零费用）
3. 视频抽帧 — ffmpeg 动态 fps 抽帧（默认 ≤12 帧），逐帧分析后汇总；临时帧用完即清理
4. 图片 base64 内容哈希缓存 — ~/.cache/vision-mcp/，同一文件不重复编码
5. 轻量会话记忆 — 进程内保留最近 N 轮问答（默认 4），多轮追问同一张图自动带上前文； memory=false 关闭、clear_memory() 清空、VISION_MCP_MEMORY=0 全局关

后端（provider）

provider	模型	端点	Key
zhipu	glm-4.6v-flash(4.6 Flash 主选) → glm-4v-flash(V4 Flash) 自动兜底（全免费）	https://open.bigmodel.cn/api/paas/v4	ZHIPU_API_KEY
qwen	qwen3.7-plus	https://dashscope.aliyuncs.com/compatible-mode/v1	DASHSCOPE_API_KEY
auto（默认）	固定走 zhipu GLM 免费家族兜底链，不切 qwen	—	—
自定义	传 base_url+api_key+model 可接任意 OpenAI 兼容端点（含 Doubao Vision）	—	—

key 读取顺序：环境变量 > ~/.qwen-mm-plugins/config > 报错。

运行

# 作为 MCP server（stdio），由 Agent 拉起：
python vision_server.py

# 依赖：仅 mcp + openai
pip install mcp openai

任意支持 MCP 的 Agent 都能接入，只需注册一个 stdio server： python /path/to/vision_server.py

ZCode 接入（已配置好）

单一插件市场 vision-mcp，插件名 vision-mcp，重启 ZCode 后即可用。 旧的双插件（qwen-mm-plugins-core / api）已移除，备份在 ~/.zcode/cli/plugins/backup-qwen-mm-plugins-*。

使用示例（发给 agent 的话术）

看下这张截图：vision_chat(images=["/path/to/s.png"], text="这是什么界面？列出全部文字")

识别这张图片文字：ocr(images=["/path/to/doc.png"])

看这个视频：vision_chat(videos=["/path/to/clip.mp4"], text="视频里发生了什么？")

定位图中物体：grounding(images=["/path/to/photo.png"], text="找到所有车辆")

用千问看这张图：vision_chat(images=[...], provider="qwen")

环境变量

变量	默认	说明
VISION_MCP_MEMORY	1	0 关闭会话记忆
VISION_MCP_MEMORY_ROUNDS	4	记忆轮数
VISION_MCP_MAX_FRAMES	12	视频抽帧上限（最大 64）

注意

• GLM 兜底链：4.6 Flash(glm-4.6v-flash) → V4 Flash(glm-4v-flash)，全是免费模型。 显式传 glm-* 模型也会挂上这条兜底链；qwen/自定义端点只试指定模型，不加别的。 整个流程默认只用免费 GLM 模型，不会调用 qwen 或其他模型。
• glm-4v-flash 的 max_tokens 上限为 1024，server 会在兜底到它时自动钳制。
• 图片支持本地路径（自动 base64）或 http(s) URL。
• dry_run=true 可预览请求结构（不真实请求，不消耗额度）。