智能视觉 MCP

给 Codex / Claude Code 提供图像识别能力的 MCP server。主模型(如 deepseek)负责推理与决策,把"看屏幕/看截图"这件事经 API 中转站分发给支持多模态的模型(默认 minimax-m3)。

目录

• 特性

• 架构

• 安装

• 更新

• 使用

• 配置(环境变量)

• 开发与测试

• 已知坑(排查用)

• 路线图(v2 候选)

• License

Related MCP server: Vision MCP Server

架构

┌─ Codex (UI 自动化) ────────────────┐
│ deepseek (无视觉, 推理/决策)        │
│   │  需要"看屏幕"时                 │
│   ▼  调用 analyze_image             │
└──────────────┬─────────────────────┘
               ▼ stdio
┌─ 本 MCP server ────────────────────┐
│ 读图 → 压缩(jimp) → data URL       │
│ → OpenAI 兼容 chat/completions     │
└──────────────┬─────────────────────┘
               ▼
        API 中转站 (minimax-m3, 视觉)

特性

• 单工具 analyze_image(image_path, prompt, json_mode?) — 传本地截图路径 + 问题,返回描述或结构化 JSON(图片字节不进模型上下文,不费主模型 token)

• 可配置 base_url / api_key / model / 超时 / 压缩参数,全部环境变量

• 一键安装 install.sh(macOS)/ install.ps1(Windows) — 自动写 Codex + Claude Code 双端配置、幂等追加 AGENTS.md 引导、安装自检

• 纯 JS 零构建 — 仅 @modelcontextprotocol/sdk + jimp 两个纯 JS 依赖,node src/index.js 直跑

• 跨平台 — macOS / Windows 同一套代码(图像压缩不再依赖平台自带命令)

• 兼容实测:中转站视觉透传、json_object、错误分类、<think> 块剥离

安装

支持 macOS 与 Windows。需要 Node.js ≥ 20。

macOS(bash):

git clone https://github.com/KOG123/visual-intelligence-mcp
cd ./visual-intelligence-mcp        # 进入克隆出的目录
bash install.sh

Windows(PowerShell):

git clone https://github.com/KOG123/visual-intelligence-mcp
cd visual-intelligence-mcp
powershell -ExecutionPolicy Bypass -File install.ps1

交互式询问三项(base_url / api_key / model),或环境变量跳过交互:

# macOS
VI_BASE_URL=https://api.xxx.com/v1 \
VI_API_KEY=sk-xxx \
VI_MODEL=minimax-m3 \
bash install.sh

# Windows(PowerShell)
$env:VI_BASE_URL="https://api.xxx.com/v1"
$env:VI_API_KEY="sk-xxx"
$env:VI_MODEL="minimax-m3"
powershell -ExecutionPolicy Bypass -File install.ps1

安装脚本做的事(两平台同一套逻辑,见 scripts/install.mjs):

完成后重启 Codex / Claude Code,MCP 列表里应出现 visual。

更新

已安装过本 MCP 的机器,更新时按变更类型对号入座:

标准更新流程(macOS 用 bash install.sh,Windows 用 powershell -ExecutionPolicy Bypass -File install.ps1):

cd ./visual-intelligence-mcp
git pull                    # 1. 拉取更新
npm install                 # 2. 仅依赖变更时执行(通常不需要)
bash install.sh             # 3. 仅规则/配置变更时执行(纯代码更新可跳过)
# 4. 重启 Codex / Claude Code 会话 ← 每次更新后必做

验证生效:重启会话后,让模型调用一次 analyze_image,或用冒烟测试确认新代码在跑:

VI_BASE_URL=... VI_API_KEY=... node test/mcp-smoke.mjs /tmp/screenshot.png "描述界面"

使用

UI 自动化中,让模型调用:

analyze_image(
  image_path: "/tmp/screenshot.png",   # 截图必须先保存为本地文件
  prompt:     "描述界面,列出所有可见按钮及其坐标",
  json_mode:  true                     # 可选,要求返回 JSON
)

• 工具描述与 AGENTS.md 已引导模型在"需要看屏幕时"主动调用,并在调用时自带具体描述要求(调用前先说明目的、prompt 写明要描述的内容);路径示例按平台生成,Windows 上工具描述显示的是 Windows 临时目录

• 截图保存到本地文件后传入绝对路径:

  • macOS:screencapture -x /tmp/screenshot.png(终端需屏幕录制权限)

  • Windows:无内置命令行截屏,可用 PowerShell 截图脚本或 Snipaste / PowerToys 等工具,保存到 %TEMP%\screenshot.png 后传入

• 拿坐标做点击:让模型以 json_mode=true 输出 [{"element": "...", "x": ..., "y": ...}]

• prompt 兜底:即使模型传了空/含糊 prompt(如"看一下"),server 也会自动补标准描述指令,结果始终可用

配置(环境变量)

配置只在安装时写入 env,改配置重跑 install.sh 即可(会提示是否覆盖)。

开发与测试

# 协议级冒烟测试(需真实网关)
VI_BASE_URL=... VI_API_KEY=... VI_MODEL=... \
  node test/mcp-smoke.mjs /tmp/screenshot.png "描述界面"

# 网关连通性验证(含 1x1 图、视觉、json_object 三段;密钥经环境变量传入)
BASE_URL=... API_KEY=... MODEL=... node test/test-gateway.mjs

# 图片压缩单元测试(纯本地,CI 双平台跑)
node test/image-unit.mjs

# 手动起服务
node src/index.js

注意:密钥一律通过环境变量提供,严禁把密钥写进脚本或提交仓库。

已知坑(排查用)

1. Codex 桌面版找不到 node — GUI 环境 PATH 不含 nvm/Homebrew 的 node,配置里 command 必须写绝对路径(install.sh 已处理为 process.execPath)。

2. ccswitch 热切换报 TOML 解析错误 — ccswitch 每次热切换重新解析 config.toml,不接受多行内联表 env = {...};配置已用标准多行表 [mcp_servers.visual.env],不要改回内联表。

3. 日志全走 stderr — stdio 传输下 stdout 只允许 JSON-RPC,任何 console.log 都会搞崩连接。

4. 中转站对未知模型名静默回退默认模型(如 deepseek,无视觉)→ 带图请求 400 报反序列化错误。报错时核对 VI_MODEL 与中转站实际模型名。

5. 重装注意:换 nvm node 版本或迁移仓库路径后,重跑安装脚本更新 command/args。

6. Windows 执行策略拦截(PowerShell Restricted)→ 用 powershell -ExecutionPolicy Bypass -File install.ps1 运行。

7. Windows 上 node 路径含空格(如 nvm-windows)→ 配置里 command 已转义为绝对路径;若 Codex/Claude Code 启动失败,检查 ~/.codex/config.toml 与 ~/.claude.json 中 command 是否指向真实 node.exe。

8. jimp 大图内存(纯 JS 解码全量加载,8K 截图峰值内存约 130MB)→ 超大截图建议先缩小再喂,或调低 VI_MAX_IMAGE_SIZE;jimp 不可用时 server 自动降级原图直发(受 VI_MAX_IMAGE_BYTES 上限约束)。

9. HEIC 不再支持(原 sips 能力,随跨平台替换下线)— iPhone 直传 HEIC 图会报"不支持的图片格式",先转成 PNG/JPEG 再传入。

路线图(v2 候选)

• 请求缓存(同图同 prompt 命中,省中转站 token)

• 截屏工具(跨平台原生截图)

• 非 OpenAI 兼容 provider(Gemini / Ollama)

• npm 打包分发(npx 一键安装)

License

MIT © 2026 kog