Skip to main content
Glama
KOG123

visual-intelligence-mcp

by KOG123
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

智能视觉 MCP

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

License: MIT Node.js ≥ 20 macOS / Windows CI PRs Welcome

目录

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):

动作

位置

依赖安装(@modelcontextprotocol/sdk + jimp,幂等)

node_modules/

Codex MCP 配置 [mcp_servers.visual] + [mcp_servers.visual.env]

~/.codex/config.toml

Claude Code MCP 配置 mcpServers.visual(user scope)

~/.claude.json

AGENTS.md 引导规则(幂等,带删除标记,路径示例按平台生成)

~/.codex/AGENTS.md

安装自检(1x1 测试图真实视觉请求,纯 Node 实现)

—

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

Node 版本受限的机器(老项目占用旧 Node)?

不需要升级系统 Node。MCP server 通过配置里的 command 绝对路径独立运行,与 PATH / 老项目互不干扰:

  1. 用 nvm-windows 安装一个新版 Node(如 22.x):nvm install 22.22.0

  2. 不要 nvm use 切换(nvm-windows 的切换是全局的,会影响之后所有新开终端的 node 指向,可能破坏老项目启动)

  3. 用新版 Node 的完整路径运行安装器(安装器把该路径写入 MCP 配置):

& "$env:APPDATA\nvm\v22.22.0\node.exe" scripts\install.mjs

或通过环境变量指定(install.ps1 检测到旧 Node 时也会自动扫描并提示这个用法):

$env:VI_NODE_BIN = "$env:APPDATA\nvm\v22.22.0\node.exe"
powershell -ExecutionPolicy Bypass -File install.ps1

安装后 Codex / Claude Code 一直用该新版本启动 MCP(需 ≥ 20,内置 fetch 依赖),老项目继续用它的旧 Node。若 nvm 装在非默认目录(如 D:\nvm),把路径换成实际位置。

更新

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

变更类型

操作

是否重跑安装脚本

server 代码更新(如功能修复)

重启 Codex / Claude Code 会话即生效

否(每次会话重新加载源码)

AGENTS.md 规则更新

重跑安装脚本(自动替换规则段,旧配置保留)

是

配置变更(模型 / 地址 / 密钥)

重跑安装脚本,覆盖时选 Y

是

依赖变化(package.json)

npm install + 重启会话

否

node 版本变更 / 仓库路径迁移

重跑安装脚本(command/args 是绝对路径,会失效)

必须

标准更新流程(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 也会自动补标准描述指令,结果始终可用

配置(环境变量)

变量

默认

说明

VI_BASE_URL

—(必填)

中转站地址,形如 https://api.xxx.com/v1

VI_API_KEY

—(必填)

中转站密钥

VI_MODEL

minimax-m3

模型名(须为支持视觉的模型)

VI_MAX_TOKENS

2048

响应 token 上限(推理模型先想后答,给足预算)

VI_REQUEST_TIMEOUT_MS

60000

请求超时

VI_MAX_IMAGE_SIZE

1280

图片最长边(px),超过等比缩放

VI_IMAGE_QUALITY

80

JPEG 质量 1–100

VI_MAX_IMAGE_BYTES

10MB

压缩后体积上限,超过报错不降质

配置只在安装时写入 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

Available Tools

1 tool
analyze_imageA

分析本地图片(UI 自动化视觉辅助)。

当需要"查看屏幕/截图/界面"时使用:传入截图路径与问题,返回多模态模型的文字描述或结构化 JSON。

调用规范(必须遵守):

  • 调用前,先在回复中说明你正在分析哪张截图及其目的(如"让我分析一下当前界面")。

  • prompt 必须写明具体想知道的描述内容,例如 "描述界面布局并列出所有可见按钮"、"截图中有哪些错误提示"、"这个弹窗的标题和选项是什么"。

  • 禁止传空 prompt 或含糊 prompt(如 "看一下"、"描述" ),server 会把过短的 prompt 视为无效并自动补充标准描述要求。

  • 图片必须已保存为本地文件,传入绝对路径;本工具自行读取,无需传图片内容。

  • 需要结构化结果(如元素坐标)时设置 json_mode=true,要求模型返回 JSON。

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes要问的问题,如"描述界面并列出可见按钮"
json_modeNo为 true 时要求模型返回 JSON(用于结构化结果,如坐标)
image_pathYes本地图片文件的绝对路径(如 /tmp/screenshot.png)

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the disclosure is strong: it warns about invalid short prompts, states the tool reads the image itself from a local path, and explains the meaning of json_mode for structured output. This goes well beyond the schema and gives the agent clear behavioral expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with a clear lead sentence followed by concise bullet-like rules, every sentence contributing value. It avoids redundancy and remains focused, making it easy to parse and apply.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 3-parameter tool with no output schema, the description fully covers prerequisites, call conventions, return format, and parameter behavior. It addresses all necessary context an agent would need to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by emphasizing that prompt must be specific (and that short prompts are auto-supplemented), requiring absolute paths, and clarifying that json_mode enables structured JSON results. This elevates the parameter understanding beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes local images for UI automation visual assistance, using the specific verb-resource pair '分析本地图片' and explicitly mentions its return type (text or structured JSON). It also specifies the use case ('当需要查看屏幕/截图/界面时使用'), making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit context for when to use the tool ('当需要查看屏幕/截图/界面时') and includes detailed call requirements (such as announcing the screenshot before calling and using a specific prompt). It does not mention alternatives or exclusions, but with no sibling tools specified, this is acceptable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap. The tool's purpose—analyzing images to answer questions or return structured data—is clear and unambiguous.

Naming Consistency5/5

The single tool name follows a clear verb_noun pattern (analyze_image) that is consistent and descriptive. There are no conflicting conventions to cause confusion.

Tool Count3/5

A single tool feels thin for a server branded as 'visual-intelligence,' but the tool itself is versatile enough to handle various image analysis requests. The count is right at the borderline where it could use additional specialized tools, but it is not wholly inappropriate.

Completeness4/5

The tool covers the core need of analyzing local images and returning either descriptive text or structured JSON, including support for UI-related queries. Minor gaps exist, such as requiring local file paths and lacking support for direct image URLs, but these are workaroundable.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/KOG123/visual-intelligence-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server