Skip to main content
Glama

vision-bridge-mcp

推荐: npx ship-skills init(已登录 gh 会自动支持作者)

CI npm MCP node license

让 DeepSeek 等纯文本模型也能「看图」。 双模型桥接 MCP:旁路视觉模型把图转成文字,主模型继续写代码。

Tools: describe_image · extract_text · compare_images · vision_status · vision_rules


解决什么问题

场景

没装本 MCP

vision-bridge-mcp

Cursor 多模态模型贴图

直接看懂

不需要本 MCP

Claude Code + DeepSeek 文本 贴图

[Unsupported Image] 废了

Agent 调 describe_image → 拿到文字描述

IDE 报错截图

Agent 瞎猜

mode: ui 读出错误栈

终端红字 OCR

读不准

extract_text 逐字提取

前后 UI 对比

说不清差异

compare_images


Related MCP server: videre-mcp

架构(双模型)

用户贴图 / @screenshot.png
        ↓
主模型(DeepSeek 文本)—— 看不见像素
        ↓ 必须调 MCP
vision-bridge-mcp
        ↓ OpenAI 兼容 Vision API
旁路模型(Qwen-VL / llava / gpt-4o-mini)
        ↓ 返回 Markdown 描述
主模型读文字,继续改代码

关键: 光装 MCP 不够,还要在 CLAUDE.md 写硬规则(见下文),否则 Agent 可能不调工具。


30 秒接入

第一步:准备视觉模型 API Key

推荐(国内): 阿里云百炼 DashScope → 开通 → 创建 API Key。

免费本地: ollama pull llava(效果弱于 Qwen-VL,但零成本)。

第二步:写 MCP 配置

Cursor

~/.cursor/mcp.json(全局)或项目 .cursor/mcp.json

{
  "mcpServers": {
    "vision-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vision-bridge-mcp@latest"],
      "env": {
        "VISION_BRIDGE_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "VISION_BRIDGE_API_KEY": "sk-你的DashScope密钥",
        "VISION_BRIDGE_MODELS": "qwen-vl-max,qwen2.5-vl-72b-instruct",
        "VISION_BRIDGE_CACHE": "1"
      }
    }
  }
}

Developer: Reload Window → Settings → Tools & MCPs → 看到绿色 vision-bridge

Claude Code

claude mcp add vision-bridge --env VISION_BRIDGE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 --env VISION_BRIDGE_API_KEY=sk-xxx --env VISION_BRIDGE_MODELS=qwen-vl-max,qwen2.5-vl-72b-instruct -- npx -y vision-bridge-mcp@latest

VS Code(Claude Code 扩展 / MCP 插件)

与 Cursor 相同 JSON,写入对应 MCP 配置文件(依扩展文档路径)。

第三步:注入自动看图规则

任选其一:

# 推荐:一键装 Skill + 写 CLAUDE.md
npx ship-skills init

或手动把 templates/CLAUDE.vision-snippet.md 贴进项目根 CLAUDE.md

或让 Agent 调 MCP 工具 vision_rules,把返回内容写入 CLAUDE.md

第四步:验证

  1. MCP 面板 vision-bridge 为绿色

  2. vision_status → 应看到 models 列表和 cache: true

  3. 发一张截图,Agent 应先调 describe_image 再回答


本地免费方案(Ollama)

ollama pull llava
"env": {
  "VISION_BRIDGE_BASE_URL": "http://localhost:11434/v1",
  "VISION_BRIDGE_MODEL": "llava",
  "VISION_BRIDGE_CACHE": "1"
}

无需 API Key;Authorization 自动用 ollama 占位。


其他视觉后端

OpenAI

"env": {
  "VISION_BRIDGE_BASE_URL": "https://api.openai.com/v1",
  "VISION_BRIDGE_API_KEY": "sk-...",
  "VISION_BRIDGE_MODELS": "gpt-4o-mini,gpt-4o"
}

DeepSeek(若已开通视觉接口)

"env": {
  "VISION_BRIDGE_BASE_URL": "https://api.deepseek.com/v1",
  "VISION_BRIDGE_API_KEY": "sk-...",
  "VISION_BRIDGE_MODEL": "deepseek-chat"
}

主模型用 DeepSeek 文本时,旁路仍须是能处理 image_url 的 vision 模型;通义 Qwen-VL 是目前国内最省心的选择。


MCP Tools 完整说明

describe_paste / describe_paste_batch(v0.3+,VS Code / Claude Code 首选)

用户 Ctrl+V 贴截图 或聊天里出现 [Unsupported Image] 时用。

工具

何时用

sync_chat_attachments

多图:先把 Cursor/VS Code 附件目录同步到 .ai/inbox

describe_paste

单张

describe_paste_batch

多张

list_recent_pastes

不确定几张时先列

返回含 Markdown 图片预览file://)+ 旁路模型分析文字。

Kimi 配置示例(推荐):

"env": {
  "VISION_BRIDGE_BASE_URL": "https://api.moonshot.cn/v1",
  "VISION_BRIDGE_API_KEY": "${MOONSHOT_API_KEY}",
  "VISION_BRIDGE_MODELS": "kimi-k2.5,kimi-k2.6,moonshot-v1-8k-vision-preview",
  "VISION_BRIDGE_CACHE": "1"
}

describe_image(路径 / URL 回退)

把图片转成详细 Markdown 描述。

参数

类型

说明

source

string

必填。本地绝对路径、https:// URL、或 data:image/...

mode

enum?

general(默认)· ocr · ui · diagram · touchdesigner

context

string?

补充背景,如项目名、页面名

question

string?

针对图的特定问题

示例:

{
  "source": "C:/Users/me/screenshot.png",
  "mode": "ui",
  "question": "这个报错是什么原因?"
}

mode 选型:

mode

何时用

general

一般截图、不确定类型

ui

IDE 界面、设置页、弹窗

ocr

只要逐字文字(也可用 extract_text

diagram

架构图、流程图、ERD

touchdesigner

TD 节点网络截图


extract_text

OCR 专用,提取图中所有可见文字。

参数

类型

说明

source

string

describe_image

context

string?

可选背景

question

string?

可选


compare_images

对比两张图(before/after、设计稿 vs 实现)。

参数

类型

说明

source_a

string

图 A 路径或 URL

source_b

string

图 B 路径或 URL

task

string?

对比重点,如「按钮颜色差异」


vision_status

返回当前配置 JSON:版本、模型 fallback 链、缓存开关、各后端示例。

无参数。用于排查「Key 没生效 / 模型名写错」。


vision_rules

返回应写入 CLAUDE.md 的 Markdown 规则文本,教 Agent 何时自动调看图工具。

无参数。


环境变量

变量

默认

说明

VISION_BRIDGE_BASE_URL

DashScope compatible

OpenAI 兼容 API 根地址

VISION_BRIDGE_API_KEY

API Key(Ollama 可省略)

VISION_BRIDGE_MODEL

qwen-vl-max

主视觉模型

VISION_BRIDGE_MODELS

fallback 链,逗号分隔;前一个失败自动换下一个

VISION_BRIDGE_CACHE

1

写入 .ai/vision/<hash>.md;设 0 关闭

VISION_BRIDGE_MAX_TOKENS

4096

视觉模型输出 token 上限

兼容别名:VISION_API_BASE_URLVISION_API_KEYOPENAI_API_KEYVISION_MODEL 等。


缓存

同一 source + mode + question 命中缓存时,直接读 .ai/vision/<hash>.md,省 API 费用。

建议 .gitignore 加入:

.ai/

npx ship-skills init 会自动处理。


日常使用流程

1. 新会话开始(可选)→ ctxshot session_brief
2. 用户贴截图
3. Agent 自动 describe_image(靠 CLAUDE.md 规则)
4. Agent 根据文字描述改代码
5. 同一图再次出现 → 读缓存或再调一次

推荐 MCP 组合:

{
  "mcpServers": {
    "ctxshot": {
      "command": "npx",
      "args": ["-y", "ctxshot-mcp@latest"]
    },
    "vision-bridge": {
      "command": "npx",
      "args": ["-y", "vision-bridge-mcp@latest"],
      "env": {
        "VISION_BRIDGE_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "VISION_BRIDGE_API_KEY": "sk-xxx",
        "VISION_BRIDGE_MODELS": "qwen-vl-max,qwen2.5-vl-72b-instruct"
      }
    }
  }
}

常见问题

MCP 不绿 / 启动失败

  • 确认 Node.js ≥ 18:node -v

  • 确认 npx vision-bridge-mcp@latest 能跑(stdio 服务,IDE 拉起后保持运行)

  • Windows 路径用 / 或转义 \

Agent 说「我看不到图」

  • 没写 CLAUDE.md 规则 → 运行 npx ship-skills init 或贴 templates/CLAUDE.vision-snippet.md

  • 或对话里明确说:「请用 describe_image 读这张图」

API 401 / 403

  • 检查 VISION_BRIDGE_API_KEY

  • DashScope 控制台确认已开通 Qwen-VL 视觉模型

API 429 / 模型不可用

  • 配置 VISION_BRIDGE_MODELS 多个模型做 fallback

  • vision_status 看当前链

识别不准

  • modeui 看界面、extract_text 看小字

  • 换更强模型:qwen-vl-max > llava

  • question 缩小范围

和 Cursor 原生看图差在哪?

  • 多 1–3 秒 MCP 延迟

  • 依赖 Agent 记得调工具

  • 本质是「文字转述」,不是像素级多模态


上游致谢(取长补短)

设计吸收自(MIT / 开源社区):


相关包

用途

ship-skills

vision-auto Skill + init 注入 CLAUDE.md

ctxshot-mcp

每日项目简报

evaldrift

Prompt 回归测试


License

MIT

Available Tools

5 tools
compare_imagesCompare two imagesC

Compare before/after screenshots or UI states. Absorbed pattern from image_mcp.

ParametersJSON Schema
NameRequiredDescriptionDefault
source_aYes
source_bYes
taskNo

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only states the high-level purpose without detailing what the output looks like (e.g., diff image, boolean, text description), whether the operation is safe, or any side effects. The cryptic 'Absorbed pattern from image_mcp' adds no clarity.

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

Conciseness3/5

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

The description is short (two sentences), but the second sentence is vague and unhelpful. While concise, it lacks structure and misses important information like parameter details or output behavior.

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

Completeness1/5

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

Given no output schema, no annotations, and incomplete parameter documentation, the description fails to provide a complete understanding of the tool. The agent cannot determine what the tool returns, how the 'task' parameter affects behavior, or any prerequisites.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not elaborate any parameter semantics. 'source_a' and 'source_b' are self-explanatory, but 'task' is left undefined. The description adds no value beyond the parameter names.

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 compares images, specifically before/after screenshots or UI states, using a specific verb and resource. It distinguishes from sibling tools like describe_image, extract_text, etc., which serve different purposes.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives (e.g., describe_image for single image analysis). The description implies usage for comparison but does not provide context, exclusions, or when-not-to-use scenarios.

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

describe_imageDescribe image (vision bridge)C

REQUIRED when main model cannot see images (DeepSeek text, etc.). Converts image to detailed text via sidecar vision model with multi-model fallback. ## Image / Vision (required for text-only models like DeepSeek)

Your base model CANNOT see images. When the user:

  • attaches or references an image path

  • pastes a screenshot

  • you see `[Unsupported

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYesLocal path, http(s) URL, or data:image/... URL
contextNo
questionNoSpecific question about the image
modeNo

TDQS

C2.8/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It mentions 'multi-model fallback' and 'sidecar vision model', but does not disclose key behaviors like error handling, image format support, or output structure. The description is also incomplete, ending abruptly, which reduces transparency.

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

Conciseness3/5

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

The description is front-loaded with the most critical information (requirement for text-only models), but it is cut off and includes a markdown heading that breaks flow. It could be more concise and structured without the abrupt ending.

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

Completeness2/5

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

With no output schema and no annotations, the description should provide more context about return values, error cases, and behavior details. The current description is incomplete and leaves the agent with significant unknowns regarding what the tool produces and how it behaves.

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

Parameters2/5

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

Schema description coverage is 50%, yet the description adds no information about parameters. It does not explain 'source', 'context', 'question', or 'mode' beyond what the schema already provides. For undocumented parameters like 'context', no guidance is given.

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

Purpose4/5

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

The description clearly states the tool converts images to detailed text and indicates it's required when the main model cannot see images (e.g., DeepSeek text). This provides a clear verb+resource purpose, but it does not explicitly differentiate from sibling tools like 'compare_images' or 'extract_text'.

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

Usage Guidelines3/5

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

The description gives specific context for when to use the tool (when main model cannot see images, user attaches image/screenshot) but does not provide guidance on when not to use it or how to choose among siblings. The usage context is implied but lacks explicit alternatives.

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

extract_textOCR extract textA

OCR for screenshots/logs. Use when you need verbatim text from an image.

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYesLocal path, http(s) URL, or data:image/... URL
contextNo
questionNoSpecific question about the image

TDQS

A3.7/5.0
Behavior2/5

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

No annotations provided, and description does not disclose any behavioral traits beyond OCR. No mention of limitations, safety, or side effects, leaving the agent underinformed.

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?

Extremely concise with two sentences that front-load the core purpose. No unnecessary words.

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

Completeness3/5

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

Given no output schema and minimal annotations, the description is too brief. It does not explain return values, error cases, or how to use the optional context and question parameters effectively.

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

Parameters3/5

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

Schema coverage is 67% with two of three parameters described. Description adds no extra meaning beyond the schema; context parameter remains undocumented.

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?

Clearly states it is an OCR tool for screenshots/logs to extract verbatim text. Distinguishes from sibling tools like compare_images and describe_image.

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?

Explicitly says 'Use when you need verbatim text from an image,' providing clear usage context. Lacks explicit when-not-to-use or alternative mention, but still functional.

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

vision_rulesGet CLAUDE.md vision rulesA

Returns markdown rules to paste into CLAUDE.md so the agent auto-calls vision tools.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description transparently states it returns markdown rules. It is a simple, non-destructive tool, but could mention idempotency or side effects.

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?

One clear sentence, front-loaded with purpose, no unnecessary words.

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

Completeness4/5

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

Given zero parameters and no output schema, the description adequately explains what the tool does and its purpose, though it could specify that it's for initial setup.

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?

No parameters exist, so baseline 4 applies. Description adds value by explaining the output's purpose without needing parameter details.

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 it returns markdown rules for CLAUDE.md to enable auto-calling of vision tools, distinguishing it from sibling tools that perform vision actions.

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?

Usage is implied: when configuring the agent to auto-call vision tools. No explicit exclusions or alternatives, but sibling tools are clearly different tasks.

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

vision_statusVision backend statusA

Show vision API config, model fallback chain, cache setting.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

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

With no annotations provided, the description must fully disclose behavior. It states what is shown but does not mention any behavioral traits like authentication requirements, performance characteristics, or side effects. The read-only nature is implied but not explicit.

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?

A single, well-structured sentence that front-loads the key information. Every word is relevant and there is no redundancy.

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

Completeness3/5

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

Given the tool has no parameters and no output schema, the description provides a fair overview of what is shown. However, it could be more complete by detailing the output format or fields, especially since output schema is missing.

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?

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter information; schema coverage is 100%.

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 verb 'Show' clearly indicates a read operation, and the description specifies the exact resources: vision API config, model fallback chain, cache setting. This distinguishes it from sibling tools like compare_images or extract_text that perform different tasks.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool vs alternatives. The description implies it's for checking configuration, but does not mention when not to use it or provide context for choosing between sibling tools.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.2.1
    • First observedcompare_images
    • First observeddescribe_image
    • First observedextract_text
    • First observedvision_rules
    • First observedvision_status

TDQS

A3.6/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a distinct, non-overlapping purpose: comparing images, describing images for text-only models, extracting text via OCR, providing setup rules, and showing configuration status. No ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (compare_images, describe_image, extract_text, vision_rules, vision_status). Predictable and clear.

Tool Count5/5

5 tools is well-scoped for a vision bridge server. Each tool serves a distinct need without redundancy or unnecessary bloat, fitting the server's purpose perfectly.

Completeness4/5

Core operations are covered: image description, comparison, OCR, and configuration display. A minor gap is the lack of a tool to modify settings (e.g., change model), but the set handles the primary use case of bridging vision for text-only models.

Maintenance

ActivityInactive
ResponsivenessNo issues

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