vision-primitives-mcp
This server equips text-only LLMs with comprehensive visual capabilities through 27 MCP tools, enabling image understanding, object localization, OCR, UI analysis, computer control, and more.
Image Understanding:
describe_image(natural language description),analyze_image(structured output with boxes/points),compare_images(multi-image comparison),compare_infer(joint reasoning with annotations).Object Localization:
locate_object(direct coordinates),som_locate(recursive Set-of-Mark grid for higher accuracy),cursor_locate(interactive cursor search),cv_locate(CV fallback for colored/templated objects).UI Parsing:
ui_parse(full UI structure: OCR, buttons, inputs, icons; optional YOLO),ui_locate(text-anchored element localization),ui_refine(VLM review and semantic correction).OCR:
ocr_image(text blocks with bounding boxes).Image Manipulation:
annotate_image(draw boxes/points/labels),crop_image,zoom_region.Advanced Reasoning:
annotate_infer(virtual annotation and spatial reasoning),reason_graph(interactive reasoning protocol).Anomaly Scanning:
scan_anomalies(grid-based detection with HD verification).Computer Control (Windows, disabled by default):
screen_capture,screen_click,screen_move,screen_drag,screen_scroll,screen_type,screen_key, and more.Diagnostics:
vision_health(backend configuration and connectivity check).
All tools support pixel or normalized (0–1000) coordinates. Multiple vision backends supported (e.g., MiMo, Qwen). Lightweight dependencies (core: Pillow). Security: SSRF protection, output sandboxing, screen control disabled by default.
Provides integration with Xiaomi's MiMo V2.5 cloud vision API, enabling tasks such as image description, object localization, OCR, and visual analysis through the MCP server.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vision-primitives-mcp What does the text in /tmp/error.png say?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Vision Primitives MCP — 给纯文本 LLM 装上眼睛的视觉原语 MCP 服务器
让纯文本模型(DeepSeek / Codex / 任意 MCP 客户端)通过 30 个 MCP 工具获得完整视觉能力:描述 → 定位(坐标)→ OCR → 标注 → 裁切/放大 → 异常扫描 → UI 结构化 → 多轮推理 → 电脑操控。视觉后端可切换(MiMo V2.5 云端 / LM Studio 本地 Qwen2.5-VL 等),单文件 Python,核心仅依赖 Pillow。
项目定位:通用视觉推理桥接层——文本模型 + 任意 VLM 的通用视觉工作流,本地隐私 + 单文件轻量。高泛化优先:核心能力(定位/切块/放大/读取)全部是纯 VLM + PIL,专用检测器(YOLO/CRAFT)只是可插拔加速器,有则加速、无则照跑。不与 UI-TARS / CogAgent 等端到端 GUI 模型竞争(它们有专门训练);核心差异化是无 grounding 模型的兜底定位与任何模型可用的多轮视觉推理。
纯文本模型(推理与决策)
│ MCP 协议(stdio, JSON-RPC 2.0)
▼
vision_primitives_mcp.py(单文件,30 工具,186 项测试)
│ OpenAI 兼容 API
▼
MiMo V2.5(云端)/ Qwen2.5-VL-7B(本地 LM Studio)/ 任意视觉 VLM实测基准(2026-08-02,程序化 ground truth)
测试图(900×600,元素位置为已知真值):红圆中心 (150,140)、绿三角中心 (740,417):

定位对比(三模型 × 多模式)


定位矩阵(同一基准图,像素级验证):
模型 | locate 红圆 | locate 绿三角 | som 红圆 | som 绿三角 | 单次调用 | ui_parse | ui_refine |
MiMo V2.5(云端) | 10-64px(波动) | 79-97px(波动) | 33-82px(波动) | 13-123px(波动) | 15-25s | 21.5s | — |
MiMo + som-cv(兜底管线) | 0px | 4px | — | — | 10-12s | — | — |
Qwen3-VL-8B(本地) | 90px | 164px | 77px | 123px | 10-30s | 29.4s | >357s |
GLM-4v-flash(智谱云) | 89px | 84px | 191px | 145px | 1.5-3.3s | — | — |
Qwen2.5-VL-7B(本地) | 28px | 27px | 15px | 123px | 1.3-1.7s | 12.4s | 12.6s |
能力矩阵(describe / OCR / 兜底定位 / 文本锚定 / 多轮推理):
模型 | describe | OCR(prompt 修复后) | som-cv(颜色目标) | ui_locate 文本锚定 | scratch 论文推理 |
MiMo V2.5(云端) | 4.7s ✓ | 8.9s,4/4 块 | 0px(3.2s) | 8.6s ✓ | 45.7s 3轮(漏答图趋势) |
Qwen2.5-VL-7B(本地) | 1.1s ✓ | 3.5-4.6s,4/4 块 | 0px | 12.8s ✓ | 9.6s 1轮全对 |
GLM-4v-flash(智谱云) | 1.5s ✓ | 2.0s,3/4 块(max_tokens≤1024 限制) | 53px(格子选偏) | — | — |
Qwen3-VL-8B(本地) | ~10s | 23s,4/4 块 | 0px | — | — |
消融:定位误差根因是"分辨率稀释"——输入 0.5x→208px / 2x→70px / 目标单独裁切→0-3px。整图定位差不是模型能力问题,是每个对象分到的视觉 token 太少;"粗定位 → 裁切 → 精定位"的管线是正解(som_locate 递归、final="cv"、text_zoom 网格均基于此)。
ZeroBench 评测(视觉推理基准,持续追踪)
ZeroBench("Impossible" 基准,发布时 SOTA 0%)评测工作流见 benchmarks/zerobench/。基线(MiMo V2.5 直答 + pass@5 采样,2026-08-02):
数据集 | 题数 | 命中 | numeric 命中率 |
主问题 | 100(numeric 84) | 2 | 2.4%(超发布时 SOTA 0%) |
子问题集 | 334(numeric 257) | 183 | 71.2% |
结论:主问题考多步组合视觉推理(模型能力瓶颈);子问题集是工具链主场——拆解后的单步问题 MiMo 直答 + 采样达 71%,验证"难题拆解 + 采样"是弱模型打硬基准的可行路径。每次模型/工具升级在此基线上重跑对比。
Related MCP server: Luma Vision MCP
工具一览(30 个)
分类 | 工具 | 作用 |
基础视觉 |
| 描述 / 结构化分析(含坐标原语) |
定位 |
| 坐标输出定位, |
| SoM 编号网格递归定位( | |
| 移动光标 + 视觉反馈循环定位(GUI-Cursor 范式,建议云端强模型) | |
| CV 兜底:颜色分割/模板匹配,像素级(numpy 加速 285x) | |
文本 |
| 逐文本块 OCR,带 bbox |
| CRAFT 文本区域检测(本地 onnx,可选加速器) | |
| 程序化切块放大读取(高泛化默认路径):网格逐块放大 VLM 精读 | |
UI 结构化 |
| YOLO 检测 + 文本锚定 + VLM 语义编辑检测框 |
图像处理 |
| 标注 / 裁切 / 放大 |
高级推理 |
| 视觉草稿纸:跨轮层栈 + 自适应裁切放大(图文论文理解) |
| 多图对比 / 联合推理 / 图形推理协议 / 虚拟标注 | |
扫描 |
| 自动异常扫描:切块候选 → 高清逐点验证(PCB 实战) |
电脑控制 |
| 截屏 + 鼠标键盘(Windows-only,安全开关默认关) |
诊断 |
| 后端配置与连通性 |
配套脚本 paper_reader.py:arXiv/URL/PDF/图片 → 多屏截图 → 分屏 scratch_think → 结构化摘要。
核心方法论
对抗分辨率稀释:一切定位精度的基础。
som_locate编号递归(模型只选格子)、final="cv"(VLM 收敛 + CV 像素级)、text_zoom网格切块(插图小字)——三个工具共享"局部放大"原理,只是块的产生方式不同(模型决策 / 检测器 / 网格)文本锚定:UI 操作指令几乎总带文字——OCR 定位文字 → 控件框。比让模型猜坐标可靠一个量级
检测器可插拔:YOLO(icon_detect)/ CRAFT(text)都是"有则加速、无则照跑"——高泛化路径(纯 VLM)始终可用
视觉草稿纸(scratch_think):无 grounding 模型缺"视觉工作记忆"——层栈把中间状态渲染回图,模型每轮可见可编辑;坐标链保证裁切放大后一切可映射回原图
几何判定程序化:重叠合并、坐标换算、收敛检测这类确定性问题交给代码,VLM 只做语义判断(实测 VLM 合并会把相邻独立元素误并)
快速上手
# ~/.codex/config.toml
[mcp_servers.vision-primitives]
command = "python"
args = ['/path/to/vision-primitives-mcp/vision_primitives_mcp.py']
startup_timeout_sec = 60
[mcp_servers.vision-primitives.env]
VISION_API_BASE = "https://api.xiaomimimo.com/v1" # 或本地 http://127.0.0.1:1234/v1
VISION_API_KEY = "你的MiMo密钥" # 本地 LM Studio 用任意占位
VISION_MODEL = "mimo-v2.5" # 或 qwen/qwen2.5-vl-7b
VISION_OUTPUT_DIR = '/path/to/vision-primitives-mcp/generated'模型选型:定位/审查/多轮推理首选 Qwen2.5-VL-7B(grounding 专才 + 非思考型,1.3-1.7s/次);MiMo 通用但定位波动大,需 VISION_SAMPLES=3;Qwen3-VL-8B 仅描述/OCR 场景考虑;GLM-4v-flash(智谱)速度优秀(1.5-3.3s)适合 describe/OCR/粗定位,定位精度弱(84-191px),且 max_tokens 上限 1024(需 VISION_MAX_TOKENS=1024)
可选增强(全部"有则加速、无则照跑"):
增强 | 放置 | 收益 |
numpy |
| 模板匹配 285x 加速 |
YOLO UI 检测 |
| ui_parse 像素级 UI 元素检测 |
CRAFT 文本检测 |
| text_detect/text_zoom 检测框加速 |
playwright |
| paper_reader 截图 |
已知边界(诚实声明)
整图定位受分辨率稀释(20-164px),用 som 递归 / final="cv" / text_zoom 对抗
极小小字(<10px):text_zoom 网格放大可读(实测 False Stop/Class Settings),但个别字符仍可能误读——模型识别极限
cursor_locate本地模型不可用(483/100px),仅云端强模型;ui_refineVLM 审查建议云端(本地 8B 数分钟)OCR 对 prompt 长度敏感(已修复,保持简短指令);表格数据首选 DOM 提取,视觉 OCR 兜底(90-120s)
平台:屏幕控制 8 工具 Windows-only;安全:URL 图片有 SSRF 防护(私网拦截)与解压炸弹限制(URL 源 50MP)
延迟:MiMo 15-25s/次、本地 Qwen2.5-VL 1.3-1.7s/次、多轮推理按轮倍增
版本历史(精简)
v1.14.1(2026-08-02):ZeroBench 评测工作流(benchmarks/zerobench):主问题 2.4% / 子问题 71.2% numeric 基线,断点续跑 + 自动判分
v1.14(2026-08-02):text_detect(CRAFT 可选)+ text_zoom(程序化切块,高泛化默认路径,实测读出 <10px 图内标注);30 工具 / 186 测试
v1.13(2026-08-02):scratch_think 视觉草稿纸(层栈 + 自适应 zoom + 坐标链);paper_reader.py 论文阅读工作流;OCR prompt 修复(召回 1→4 块);extract_json 截断容错
v1.12(2026-08-02):ui_refine 检测框语义编辑(VLM 删除误检/标注 + 程序化几何合并)
v1.11(2026-08-02):ui_parse / ui_locate(UI 结构化 + 文本锚定)+ YOLO 可选检测 + SSRF/解压炸弹防护 + numpy 模板匹配
v1.10(2026-08-02):som_locate(SoM 编号递归,final=box/number/cv)+ cursor_locate + cv_locate
v1.9(2026-08-02):Computer Use(8 个屏幕控制工具,安全开关)
v1.7-1.8:refine 两阶段精修(70→20px)、reason_graph、annotate_infer、坐标格式实验(像素最稳)
v1.1-1.6:scan_anomalies(PCB 实战)、compare_images、中文 OCR 修复
v1.9.1 / v1.13.3 修复记录:MCP 响应帧 jsonrpc/id(严格客户端兼容)、长 JSON 截断容错
测试与安全
python test\run_tests.py # 186 项 mock 测试,不依赖真实 key
python test\e2e_mimo.py # 真实端到端(需要 VISION_API_KEY)输入图片只读,上传仅发往配置的后端;
out_path强制限定输出目录URL 图片:SSRF 防护(私网/链路本地/元数据拦截,回环放行)+ 解压后 50MP 限制
API key 仅存本地配置;屏幕控制类工具默认拒绝(
VISION_ALLOW_SCREEN_CONTROL=1启用)
Available Tools
27 toolsanalyze_imageB
结构化分析:返回 description + visual_primitives(box/point 坐标与标签)。
Inputs: image (required), format, question.
annotate_imageA
在图片上画矩形框/圆点/标签(圈画标记),保存标注图并返回路径。
Inputs: image (required), items (required), style, coords, +1 more.
annotate_inferA
虚拟标注 + 增强图形推理:把框/点/连线/箭头/圆等标注(不修改原图)注入视觉模型,引导空间关系推理。mode=virtual 用坐标文本注入;mode=overlay 生成半透明叠加图。
Inputs: image (required), items (required), question (required), mode, +4 more.
compare_imagesA
多图对比分析(2-4 张):A/B 截图对比、设计稿一致性、多帧分析,返回逐项对比结果。
Inputs: images (required), detail, question.
compare_inferA
多图联合推理(2-4 张):每张图可带独立标注(items_per_image),联合对比/推理关系(差异、因果、时序、整体结论)。
Inputs: images (required), question (required), mode, alpha, +1 more.
crop_imageA
按坐标裁切图片(可边缘外扩),保存并返回路径与新尺寸。
Inputs: box (required), image (required), coords, out_path, +1 more.
cursor_locateA
移动光标 + 视觉反馈循环定位:渲染光标位置,模型输出目标相对光标的偏移(dx/dy),逐步逼近目标中心。对相对偏移的估计比绝对坐标更准(参考 GUI-Cursor 交互式搜索范式)。
Inputs: image (required), target (required), start, coords, +3 more.
cv_locateA
传统 CV 精定位(备选方案):颜色分割 + 连通域质心(像素级,零依赖,实测 0-4px)或模板匹配。适用简单目标(纯色 UI 元素、几何图形、固定模板);泛化有限,通用目标请用 locate_object / som_locate。
Inputs: image (required), target (required), color, coords, +2 more.
describe_imageB
用视觉模型描述图片内容,返回文字描述。
Inputs: image (required), detail, question.
locate_objectB
在图片中定位目标对象,返回坐标 primitives(让 LLM 输出坐标)。找不到会返回 count=0。
Inputs: image (required), target (required), coords, refine.
ocr_imageB
OCR 提取图片中所有文字块,返回 text + bbox(像素与归一化坐标)。
Inputs: image (required), language.
reason_graphB
交互式图形推理协议:原语(locate/measure) → 语义(semantic/hypothesis) → 标注(annotate/verify) 多轮循环。session 跨轮传递状态。
Inputs: step (required), image (required), session, question.
scan_anomaliesA
自动扫描图片中的异常/歪斜元件:把区域切成带重叠的块逐块定位候选,再从原图高清裁切逐个验证,输出带置信度与角度/丝印的报告。
Inputs: image (required), region, target, verify, +3 more.
screen_captureA
截屏(全屏或指定区域),保存 PNG 并返回路径。配合 locate_object/describe 实现「看屏幕」。
Inputs: region, out_path.
screen_clickA
鼠标点击(需 VISION_ALLOW_SCREEN_CONTROL=1)。坐标通常来自 locate_object 对截图的定位结果。
Inputs: x (required), y (required), button, double.
screen_dragC
鼠标拖拽(需 VISION_ALLOW_SCREEN_CONTROL=1)。
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +2 more.
screen_infoC
屏幕信息:分辨率、DPI、电脑控制开关状态。
Inputs: no named parameters.
screen_keyA
按键或组合键(需 VISION_ALLOW_SCREEN_CONTROL=1)。如 enter / tab / ctrl+c / alt+tab。
Inputs: key (required).
screen_moveC
仅移动鼠标光标(需 VISION_ALLOW_SCREEN_CONTROL=1)。
Inputs: x (required), y (required).
screen_scrollA
滚轮滚动(需 VISION_ALLOW_SCREEN_CONTROL=1)。正数向上,负数向下。
Inputs: delta (required).
screen_typeA
键盘输入文本(需 VISION_ALLOW_SCREEN_CONTROL=1)。ASCII 直接按键;中文等经剪贴板粘贴。
Inputs: text (required).
som_locateA
Set-of-Mark 编号网格递归定位:叠加编号标记,模型回答目标所在编号,逐轮裁切放大收敛;final=box(默认)时末轮在局部图上直接输出坐标框,精度远高于整图直接定位。对无 grounding 训练的通用 VLM(MiMo 等)比直接输出坐标更准。
Inputs: image (required), target (required), grid, color, +5 more.
ui_locateA
UI 元素定位(文本锚定优先):目标描述 → 关键词 → OCR 文本匹配 → 控件框(像素级)。按钮/输入框/图标等 UI 点击类目标的备选精定位;返回 matched + 候选列表供 VLM 确认。
Inputs: image (required), target (required), type, coords.
ui_parseA
全屏 UI 结构化解析:OCR 文本块 + 矩形控件检测(button/input)+ 图标候选 + 可选 YOLO 检测器(OmniParser icon_detect,models/icon_detect.pt 存在时自动启用),输出带 id 的结构化元素列表。out_path 保存半透明叠加层渲染图(编号框),可直接交 VLM 做编号选择。
Inputs: image (required), coords, out_path.
ui_refineA
VLM 审查并语义修正 UI 检测框:删除误检 / 合并重复 / 语义标注 / 文本锚定补漏。不做坐标微调(坐标级修正由 som/cv 负责)。返回修正后元素列表与变更记录。
Inputs: image (required), coords, out_path.
vision_healthA
检查视觉后端配置与连通性。
Inputs: no named parameters.
zoom_regionB
放大图片指定区域(默认整图 2 倍),保存并返回路径。
Inputs: image (required), box, scale, coords, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Multiple tools overlap significantly in purpose: locate_object, som_locate, cursor_locate, and cv_locate all return coordinates; describe_image, analyze_image, and compare_image/compre_infer all analyze visual content. While each has a distinct method, an agent would struggle to choose the right one without carefully parsing dense descriptions.
Tool names mix conventions: some use verb_noun (describe_image, crop_image), others use prefix_verb (ui_locate, cv_locate, som_locate), and a few are noun-y (vision_health, reason_graph). Even within the screen_* group, screen_capture vs screen_click are inconsistent in verb placement. This makes the naming unpredictable.
With 27 tools, the server exceeds the range where each tool feels essential. Several tools (e.g., cursor_locate vs som_locate, compare_infer vs compare_images) could be merged, and the count feels heavy for a 'vision primitives' server.
The toolkit covers a broad range: OCR, description, structured analysis, localization, annotation, cropping, UI parsing, multi-image comparison, anomaly scanning, and screen control. There are few obvious gaps for a vision-oriented server, though some overlapping implementations suggest room for consolidation.
Related MCP Connectors
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
MCP server for Qwen Image 3 AI image generation
MCP-Native LLM Orchestration Agent
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides 8 vision tools for UI screenshot to code, OCR, error diagnosis, diagram understanding, data visualization analysis, UI diff, and image/video analysis, plus model list query, powered by SiliconFlow's multimodal API.GPL 3.0
- AlicenseAqualityDmaintenanceAn MCP server that adds visual understanding to text-only LLMs via image understanding, OCR, and image comparison tools, with multi-provider fallback and context-aware Focus Hint for precise descriptions.3MIT
- FlicenseAqualityDmaintenanceAn MCP server for image understanding via OpenAI-compatible vision models, offering tools for OCR, error screenshot diagnosis, technical diagram reading, data visualization analysis, UI-to-code conversion, and UI diff comparison.7-
- AlicenseNot gradedqualityBmaintenanceMCP server for multimodal understanding and object grounding (bounding boxes) across images, videos, and documents, with support for multiple AI providers (Zhipu GLM-V, OpenAI GPT-4o, Anthropic Claude, or any OpenAI-compatible endpoint).1MIT