Local Vision MCP（本地识图）

给纯文本模型（DeepSeek 等）补上本地"看图"能力：MCP 优先、命令行兜底，图片全程不出本机。

English | 简体中文

Give pure-text LLMs (DeepSeek, Claude, Codex, etc.) local vision. Image files and vision processing stay on your machine — a local Ollama vision model, PaddleOCR text recognition, YOLO detection/segmentation, and OpenCV locating return text and coordinates. Raw images are never uploaded directly. Full English docs: README.en.md

图片文件与视觉识别全程在本机完成：读取本地图片 → 本地 Ollama 视觉模型 / YOLO / PaddleOCR / OpenCV → 返回文字与坐标，原始图片不直接上传。 识别出的文字会进入主模型对话——若主模型为云端 API（如 DeepSeek），该文字内容会上云；需要完全隔离可搭配本地主模型。

特性

• 🖼️ 本地看图：图片文件与视觉识别全程在本机完成，不直接上传原图；识别出的文字随对话交给主模型（云端主模型可见）

• 🔧 专业工具分工：视觉模型描述、PaddleOCR 场景文字识别（含坐标框）、YOLO 检测/分割、零样本检测、颜色/模板定位、裁切放大，各管一段

• 🔄 多轮识图闭环：概览 → 聚焦 → 文字 → 定位 → 放大 → 交叉校验 → 综合报告，过滤幻觉

• ⚡ 快慢双模式：顺手附图走 quick（默认 4B、秒级返回），认真分析走 detailed（8B）

• 🧠 健壮性：相同图片+参数自动缓存（秒回）、Ollama 瞬时故障自动重试、图片内容按"不可信数据"处理（防提示注入）、vision_status 一键排障

• 🛡️ 部署友好：server 零依赖起步；PaddleOCR / YOLOE 等重型能力可选、自动降级；下载支持断点续传与完整性校验

• 📦 开箱脚本：环境自检、MCP 注册、skill 安装、可选依赖一键装

Related MCP server: image_mcp

效果演示

同一张看板截图的真实工具输出：cv_locate 颜色定位（绿/红卡片色条）+ PaddleOCR 文字识别（含坐标）+ 本地 qwen3-vl 综合分析（图片文件在本机处理）：

为什么有这个东西

DeepSeek 等纯文本模型没有视觉能力，但通过 MCP 工具可以获得"看图"能力：由本地视觉模型负责"看"，主模型负责"想"。 本项目把看图拆成多个专业工具（描述、OCR、检测、定位、裁切放大），再用多轮闭环 skill 串起来，解决单次调用漏细节、位置说不准、幻觉等问题。

原理

一句话：主模型负责"想"，本地引擎负责"看"，MCP 是桥，skill 是流程；图片文件与视觉识别在本机完成。

数据流：纯文本主模型（Codex / Claude Code / opencode / DeepSeek 等）→ server.py（MCP stdio，12 个工具）→ 本地引擎（Ollama 视觉模型 / PaddleOCR / YOLO / OpenCV / Pillow）→ 返回文字与坐标 → 主模型交叉校验并输出最终报告。

文件

server.py                  MCP 服务器本体（单文件，基础零依赖）
call_tool.py               命令行调用工具（MCP 不可用时的 CLI 兜底）
register_mcp.py            安全注册 MCP 的 Python 实现
check_mcp.py               MCP 连通性握手探针
AGENTS.md                  识图规范（Codex 自动加载，场景 → 工具映射）
win_ocr.ps1                Windows 内置 OCR 调用脚本
skills/vision-perceive/    多轮识图闭环 skill
tests/                     离线单元测试 + 真机冒烟测试
docs/                      架构说明 / 部署手册 / 开发记录
check.ps1                  环境自检
setup.ps1 / install.ps1 / install-extra.ps1 / register-mcp.ps1 / install-skill.ps1   安装与注册脚本
examples/                  合成示例图与展示图（demo_input / demo_annotated / social_preview / architecture）
benchmarks/                 可复现基准测试（合成用例 + 指标报告，见「测试」一节）
LICENSE / CHANGELOG.md / CONTRIBUTING.md / requirements.txt

环境要求

• Python 3.9+

• Ollama 已安装并启动，视觉模型：ollama pull qwen3-vl:8b

• 可选：python -m pip install -r requirements.txt（Pillow / ultralytics / numpy）

安装（两种方式，任选其一）

安装完成后重启 Codex 即可使用。下方"工具/功能/排障"等章节均为参考材料，安装阶段不必通读。

方式一：一键安装（推荐）

# 基础安装（描述 / 检测 / 分割 / OCR 兜底）
powershell -ExecutionPolicy Bypass -File setup.ps1

# 完整安装（+ PaddleOCR 场景文字 / YOLOE 零样本，需联网，体积较大）
powershell -ExecutionPolicy Bypass -File setup.ps1 -Extras

setup.ps1 = 环境检查 +（可选依赖）+ 注册 MCP + 安装 skill 的整合脚本，可重复执行（幂等）。

⚠️ 注册 MCP 前请先完全退出 Codex 桌面应用，注册完再启动；运行中的应用可能用旧配置覆盖你的修改。register-mcp.ps1 检测到 Codex 在运行时会自动中止。

方式二：分步安装（想看清每一步）

# 0. 环境准备（一次性）
#    安装 Python 3.9+（https://www.python.org/downloads/）
#    安装并启动 Ollama（https://ollama.com）
ollama pull qwen3-vl:8b

# 1. 自检环境
powershell -ExecutionPolicy Bypass -File check.ps1

# 2.（可选）安装 PaddleOCR / CLIP（不装则 OCR 自动回退 Windows OCR）
powershell -ExecutionPolicy Bypass -File install-extra.ps1

# 3. 注册 MCP（只追加 local_vision，不会动你已有的 DeepSeek 配置）
powershell -ExecutionPolicy Bypass -File register-mcp.ps1

# 4. 安装识图 skill
powershell -ExecutionPolicy Bypass -File install-skill.ps1

# 5. 重启 Codex，然后说：分析这张图 C:/xxx/photo.png

工具

命令行直接用（CLI 兜底）

如果客户端没有把 MCP 工具注入当前会话（工具列表里看不到 analyze_image / ocr_extract 等）， 可以直接用命令行调用同一套本地工具，效果与 MCP 完全等价：

python call_tool.py <工具名> '<JSON 参数>'

示例：

• 看图说话：python call_tool.py analyze_image '{"file_path":"C:/x.png","mode":"quick"}'

• 提取文字：python call_tool.py ocr_extract '{"file_path":"C:/x.png","engine":"auto"}'

• 数人/找物体：python call_tool.py detect_objects '{"file_path":"C:/x.png","classes":["person"]}'

不带参数运行会列出全部 12 个工具。vision-perceive skill 已内置该兜底：MCP 工具不可用时自动改用 CLI， 不会因为客户端没注入工具而跳过识图。

提示：在 Codex 桌面端等环境下，命令行里的双引号可能被外壳吞掉，直接传 JSON 参数会报"JSON 解析失败"。 此时改用 --args-file：先用文件编辑器把参数写成 JSON 文件，再执行 python call_tool.py <工具名> --args-file <参数文件>（详见 docs/识图使用指南.md）。

定位工具箱（该用哪个）

中文描述会自动本地翻译成英文再检测（常见物体走词典直译，其余走本地 Ollama 翻译；LOCAL_VISION_ZS_TRANSLATE=0 可关闭）。

多轮识图闭环（vision-perceive skill）

收到图片分析请求时，按 skill 流程执行而不是单次调用： 概览 → 聚焦 → 文字提取 → 精确定位 → 局部放大 → 交叉校验 → 综合报告。 多轮一致的内容可信度高，单轮幻觉会被过滤；小字小目标强制先放大再识别。

如何唤起

• 显式唤起：对话里输入 @vision-perceive 后跟图片请求（例如 @vision-perceive 分析这张图），强制按该流程执行；

• 自动生效：以本目录为工作区的新对话，AGENTS.md 会自动注入识图规范（含 CLI 兜底），无需任何前缀。

目标检测依赖

python -m pip install ultralytics

• detect_objects 默认 yolov8n.pt（首次自动下载约 6MB，可 DETECTION_MODEL 换 yolov8s.pt 等）

• detect_by_text 默认 yoloe-v8s-seg.pt（首次自动下载约 30MB），也可换 yolov8s-world.pt

detect_by_text（YOLOE）还需要 CLIP 文本编码依赖，否则会报 No module named 'clip'：

python -m pip install git+https://github.com/ultralytics/CLIP.git

GitHub 不通时用镜像（任选其一）：

python -m pip install git+https://ghproxy.net/https://github.com/ultralytics/CLIP.git
python -m pip install git+https://ghfast.top/https://github.com/ultralytics/CLIP.git

首次调用 YOLOE 还会联网下载 CLIP 权重（ViT-B/32，约 300MB）。

另外 YOLOE 的文本编码器需要 MobileCLIP 的 TorchScript 权重 mobileclip_blt.ts（约 530MB）。服务端会在首次调用 detect_by_text 时后台自动从镜像下载到项目目录（默认 ghproxy 镜像，可用环境变量 MOBILECLIP_TS_URL 更换）。 下载不阻塞调用：工具会立即返回进度，稍后重试即可继续。也可手动下载：

curl -L -o mobileclip_blt.ts "https://ghproxy.net/https://github.com/ultralytics/assets/releases/download/v8.4.0/mobileclip_blt.ts"

ghproxy 对大文件可能中途截断；若失败，改用 GitHub 直连（release 资源通常可达）：

curl.exe -L -C - -o mobileclip_blt.ts "https://github.com/ultralytics/assets/releases/download/v8.4.0/mobileclip_blt.ts"

不想等 530MB 的话：detect_by_text 可以立即改用 YOLO-World（约 25MB，文本编码内置，不需要 CLIP/mobileclip）。 调用时传 model="yolov8s-world.pt" 即可，权重缺失时服务端会自动后台从镜像下载。

可选依赖可一键安装：

powershell -ExecutionPolicy Bypass -File install-extra.ps1

提速说明（顺手带图别再等几分钟）

• 快速模式：analyze_image(mode="quick") 用 4B 模型（未安装自动回退 8B）、精简 prompt 控输出、上下文 4096，单次约 10~30 秒。skill 已规定：顺手附图只调一次 quick，不跑多轮。

• 详细模式：analyze_image(mode="detailed") 用 8B 完整描述，仅在用户要求仔细分析时使用。

• 显存：num_ctx 改小可省显存（8B 在 8GB 显存下会 20% 层跑 CPU，这是主要慢因）。

• 想更快：ollama pull qwen3-vl:4b 后快速模式自动使用。

提前下载零样本模型（可选，避免第一次调用等下载）：

python -c "from ultralytics import YOLO; YOLO('yoloe-v8s-seg.pt')"

健壮性与安全（v2.3）

• 结果缓存：analyze_image / ocr_extract 对"相同图片内容 + 相同参数"自动命中缓存（按内容哈希，文件被替换会自动失效）， 第二次调用秒回，不用重复等本地模型推理。可用 LOCAL_VISION_CACHE=0 关闭。

• 自动重试：Ollama 瞬时故障（HTTP 429/5xx、网络抖动）自动指数退避重试（默认 2 次），模型不存在（404）不重试，直接给出安装提示。

• 不可信数据防护：图片可能包含诱导性文字（如"忽略之前的指令"），因此 analyze_image / ocr_extract 的返回都带 [安全提示] 前缀，提醒主模型把图片内容当数据、不当指令。

• 输入校验：主要看图工具要求绝对路径，并按文件真实内容（magic-byte）校验格式，扩展名造假或传错文件会得到明确报错而非奇怪的解析错误。

• 可选大图缩放：LOCAL_VISION_MAX_DIMENSION（默认关闭）可让超长边大图在发给 Ollama 前自动等比缩小，防止 detailed 模式卡死； 注意整图缩放会损失全局细节——需要精度的场景仍然先用 crop_image 裁出目标区域放大，那个路径不受影响。

• 一键排障：vision_status 输出版本、Ollama 连通性、两个视觉模型是否已安装、可选依赖状态、缓存/重试配置， 遇到"连不上 / 没模型 / 缺依赖"先调它。

测试

python tests\test_server.py
python tests\test_edge_cases.py
python tests\test_robustness.py
python tests\test_cli.py

离线测试用 mock Ollama 验证协议与全部工具，共 98 项：test_server.py 37 项（analyze / 缓存 / 瞬时错误重试含 429 / 多图逐张 / 拼图对比 / 相对路径拒绝 / 伪格式拒绝 / 超大图拒绝 / crop / draw / cv_locate / 错误路径 / 输出目录限制 / 零样本翻译桥等）+ test_edge_cases.py 22 项（EXIF 方向 / 透明图白底 / 非法颜色报错 / scale 内存上限 / 反向坐标 / 格式兼容 / 定位边界）+ test_robustness.py 28 项（缓存 TTL/淘汰/并发 / Ollama 主机归一化 / Paddle 解析防御 / 检测格式化 / 拼图极端 / 工具 schema / 输出覆盖保护 / 基准工具函数）+ test_cli.py 11 项（CLI 兜底：用法 / 未知工具 / 坏 JSON / 直参 / args-file / stdin / 错误码）。

另有基准测试（量化精度，合成图 + 标准答案，可复现）：

python benchmarks\generate_cases.py
python benchmarks\run_benchmark.py

覆盖 OCR（中/英/表格/小字）、颜色定位与计数、模板匹配、裁切、输入校验，报告输出到 benchmarks\report\。指标口径与自定义检测数据集格式见 benchmarks\README.md。

开源与许可

• 本项目代码：MIT License。

• 模型权重不随仓库分发：yolov8n.pt / yoloe-*.pt 等为 AGPL-3.0 许可（Ultralytics），首次调用自动下载，用户自担许可责任。

• 绝不提交：config.toml（含 DeepSeek API Key）、*.bak-*、.cache/、真人照片测试图（.gitignore 已屏蔽）。

• 图片文件仅在本机处理（本地 Ollama / PaddleOCR / YOLO / OpenCV），不直接上传原图；对话内容（含识别文字）按你所使用的主模型策略发送。

配置项（环境变量）

部署与排障

• Roadmap — 项目方向与规划（近期做啥 / 明确不做啥）

• 识图使用指南 — 场景 → 工具速查（含 CLI 示例）

• 架构说明 — 设计目标、分层、数据流、设计决策、扩展点

• 部署与常见问题（用户向） — 照做即可部署，按症状查问题

• 开发记录与踩坑（内部） — 开发过程所有问题的根因与对策

已知限制

• qwen3-vl:8b 定位能力弱：能验证框、描述场景、读文字，但直接输出精确坐标不可靠——因此定位交给 YOLO/OpenCV。

• 识别文字随对话上云：图片文件不出本机，但 OCR / 描述等识别文字会进入主模型对话；若主模型为云端 API（如 DeepSeek），这些文字会发送到其服务器。需要完全隔离时可搭配本地主模型（如 Ollama 中的 qwen3 / deepseek-r1）。

• 零样本检测的中文描述依赖本地翻译：常见物体走词典直译，其余靠本地 Ollama 翻译（约几秒）；Ollama 未运行时仅词典词可用，复杂描述建议直接用英文。

• qwen3-vl 设置 num_predict（max_tokens）会返回空输出（实测 Ollama 行为），所以限长靠精简 prompt 而不是参数。

• 多图策略：qwen3-vl 一次只认一张图，所以 analyze_image(file_paths=[...]) 会逐张分析后合并返回（每张都完整看）；用户明确要求"对比/有什么区别"时用 compare_images（拼图对比）。拼图会缩小单图，细节场景请分别 analyze_image。

• OCR 有误读率：系统 OCR 偶发识别错误，重要文字建议与视觉模型交叉核对；艺术字/手写效果差。

• OCR 坐标在 PowerShell 5.1 下为 0：仅指 Windows 内置 OCR 兜底路径（WinRT 限制）；使用 PaddleOCR 引擎时坐标正常。安装 PowerShell 7 后兜底路径的坐标也可用。

• 8B 模型速度：每次识图约 20~60 秒，可换 4B 提速。

• 模板匹配对纯色模板失效：请裁取含纹理/边缘的区域作为模板。

• PaddleOCR 可能自动回退 Windows OCR：auto 模式下若 PaddleOCR 初始化失败（最常见是进程对 %USERPROFILE%\.paddlex 没有写权限，例如沙盒 / 受限环境 / 部分杀软拦截），会自动回退系统 OCR，并在返回文本里注明"已回退 Windows OCR"——这不是故障，回退后仍可正常识别，只是精度略低、中文表格等场景更易误读。想强制使用 PaddleOCR 可显式传 engine="paddle"（初始化失败会直接报错，方便定位）；普通终端里运行一般不会触发回退。

兼容性（换工具 / 换模型 / 换平台）

本项目按标准 MCP 协议设计，视觉能力与主模型、客户端解耦。已实测：server 协议 + CLI 兜底在 Codex + DeepSeek（Windows）下可用； 以下组合按标准协议兼容，未逐项实测，遇到问题按"部署与常见问题"排查。

需要说明的前提：MCP 工具能否被调用，取决于客户端是否把它注入当前会话——这是客户端行为，与 server 无关 （例如部分桌面端对第三方模型通道不注入 MCP 工具，官方自带的 MCP 服务器可能同样不注入）。因此：

• 客户端支持 MCP 工具调用时，本项目直接可用；

• 客户端未注入 MCP 工具时，CLI 兜底保证仍然可用：python call_tool.py <工具名> '<JSON 参数>'，与 MCP 工具完全等价（见「命令行直接用」一节）；

• 具体场景怎么选工具，见 docs/识图使用指南.md。

1. 换主模型（脑）

server.py 不依赖 DeepSeek，只认 MCP 协议。只要你的客户端支持 MCP 工具调用，任何主流模型 （Claude、GPT、Qwen、GLM、Kimi 等）都能作为"脑"使用——在客户端里切换模型即可，本项目无需改动。 工具描述为中文，主流模型均可正确读取。

2. 换客户端（工具）

把 server.py 注册成标准 MCP stdio 服务即可：

{
  "mcpServers": {
    "local_vision": {
      "command": "python",
      "args": ["C:/绝对路径/server.py"]
    }
  }
}

提示：register-mcp.ps1 已自动写入当前环境的 Python 绝对路径；如果手动配置，建议把 command 写成该环境的 Python 绝对路径 （如 E:/miniconda3/python.exe），避免客户端进程没有继承虚拟环境 PATH 时找到错误解释器（如微软商店占位程序）。

换客户端后的常见坑

粘贴的图片去哪了？ 各客户端把粘贴图片落盘的位置不同，analyze_image 需要的是图片路径：

Windows 剪贴板的坑：在资源管理器里对图片"复制"（Ctrl+C）复制的是文件路径列表而不是图片内容， 在 CLI 客户端里直接粘贴不一定生效；把图片文件拖进对话框（插入路径）最稳。

宿主超时建议：本地视觉推理比纯文本慢（4B 约 1030s、8B 约 2060s），部分宿主默认 MCP 超时只有 30~60 秒， 首次调用或大图时可能被宿主掐断。建议把该 MCP 服务的超时调到 120000ms 以上（Codex 对应 startup_timeout_sec， 其他客户端在 MCP 配置里找 timeout/timeoutMs 字段）。

3. 换视觉模型（眼）

Ollama 上任意视觉模型都可用：

ollama pull qwen3-vl:4b        # 快速模式（更小更快）
ollama pull llava:13b          # 或 llava / gemma3-v 等其他视觉模型

通过环境变量或调用参数切换：OLLAMA_VISION_MODEL（detailed）、VISION_MODEL_QUICK（quick）、或 analyze_image 的 model 参数。

4. skill 移植（可选）

• Codex：install-skill.ps1 一键安装

• Claude Code：skill 就是标准 SKILL.md（YAML frontmatter + Markdown），直接复制 skills/vision-perceive 到项目 .claude/skills/ 或 ~/.claude/skills/ 即可，格式天然兼容

• Cursor / Trae 等：没有原生 skills，但 MCP 工具本身可用；把 SKILL.md 里的"模式决策 + 多轮流程"复制进 rules/自定义指令即可获得同等闭环效果

5. 平台说明

• Windows：完整测试路径（含 Windows 内置 OCR 兜底）

• Linux / macOS：server.py、Ollama、ultralytics、PaddleOCR 均跨平台可用；但 win_ocr.ps1（Windows OCR 兜底）不可用，OCR 需依赖 PaddleOCR（跨平台），或自行接入 tesseract 等

• .ps1 安装脚本仅 Windows；其他平台按上面的 MCP 配置 JSON 手动注册即可

明确不兼容 / 注意

• file_paths 多图是逐张分析后合并返回；"对比"请用 compare_images（拼图对比，单图会缩小）

• 坐标类任务请走检测/分割工具，别指望任何视觉模型直接报坐标

常见问题

• 连不上 Ollama：确认系统托盘有 Ollama 图标，或命令行先跑 ollama list。

• 报"模型不存在"：先 ollama pull qwen3-vl:8b。

• 检测报"需要联网下载权重"：首次使用需联网下载模型权重，网络通后重试。

• 改了代码没生效：重启 Codex（工具列表是启动时加载的）。