vision-bridge-mcp
This server bridges vision capabilities to text-only LLMs (like DeepSeek), enabling them to "see" and understand images by routing them through a sidecar vision model (e.g., Qwen-VL, LLaVA, GPT-4o-mini) and returning text descriptions.
describe_image— Convert any image (local path, HTTPS URL, or base64 data URI) into a detailed Markdown description. Supports modes:general,ocr,ui,diagram, andtouchdesigner, plus optional context and specific questions.extract_text— Perform OCR to extract verbatim visible text from screenshots, logs, or any image.compare_images— Analyze two images (e.g., before/after, design vs. implementation) and describe their differences. Accepts an optional task description to focus the comparison.vision_status— Show the current vision API configuration, active model fallback chain, cache settings, and version info — useful for debugging.vision_rules— Generate Markdown rules to paste intoCLAUDE.md, instructing the agent to automatically call vision tools whenever images are encountered.
Click on "Install 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-bridge-mcpDescribe this error screenshot and explain the issue"
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-bridge-mcp
⭐ 推荐:
npx ship-skills init(已登录gh会自动支持作者)
让 DeepSeek 等纯文本模型也能「看图」。 双模型桥接 MCP:旁路视觉模型把图转成文字,主模型继续写代码。
Tools:
describe_image·extract_text·compare_images·vision_status·vision_rules
解决什么问题
场景 | 没装本 MCP | vision-bridge-mcp |
Cursor 多模态模型贴图 | 直接看懂 | 不需要本 MCP |
Claude Code + DeepSeek 文本 贴图 |
| Agent 调 |
IDE 报错截图 | Agent 瞎猜 |
|
终端红字 OCR | 读不准 |
|
前后 UI 对比 | 说不清差异 |
|
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@latestVS 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。
第四步:验证
MCP 面板
vision-bridge为绿色调
vision_status→ 应看到models列表和cache: true发一张截图,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] 时用。
工具 | 何时用 |
| 多图:先把 Cursor/VS Code 附件目录同步到 |
| 单张 |
| 多张 |
| 不确定几张时先列 |
返回含 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 描述。
参数 | 类型 | 说明 |
| string | 必填。本地绝对路径、 |
| enum? |
|
| string? | 补充背景,如项目名、页面名 |
| string? | 针对图的特定问题 |
示例:
{
"source": "C:/Users/me/screenshot.png",
"mode": "ui",
"question": "这个报错是什么原因?"
}mode 选型:
mode | 何时用 |
| 一般截图、不确定类型 |
| IDE 界面、设置页、弹窗 |
| 只要逐字文字(也可用 |
| 架构图、流程图、ERD |
| TD 节点网络截图 |
extract_text
OCR 专用,提取图中所有可见文字。
参数 | 类型 | 说明 |
| string | 同 |
| string? | 可选背景 |
| string? | 可选 |
compare_images
对比两张图(before/after、设计稿 vs 实现)。
参数 | 类型 | 说明 |
| string | 图 A 路径或 URL |
| string | 图 B 路径或 URL |
| string? | 对比重点,如「按钮颜色差异」 |
vision_status
返回当前配置 JSON:版本、模型 fallback 链、缓存开关、各后端示例。
无参数。用于排查「Key 没生效 / 模型名写错」。
vision_rules
返回应写入 CLAUDE.md 的 Markdown 规则文本,教 Agent 何时自动调看图工具。
无参数。
环境变量
变量 | 默认 | 说明 |
| DashScope compatible | OpenAI 兼容 API 根地址 |
| — | API Key(Ollama 可省略) |
|
| 主视觉模型 |
| — | fallback 链,逗号分隔;前一个失败自动换下一个 |
|
| 写入 |
|
| 视觉模型输出 token 上限 |
兼容别名:VISION_API_BASE_URL、VISION_API_KEY、OPENAI_API_KEY、VISION_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_KEYDashScope 控制台确认已开通 Qwen-VL 视觉模型
API 429 / 模型不可用
配置
VISION_BRIDGE_MODELS多个模型做 fallback调
vision_status看当前链
识别不准
换
mode:ui看界面、extract_text看小字换更强模型:
qwen-vl-max>llava加
question缩小范围
和 Cursor 原生看图差在哪?
多 1–3 秒 MCP 延迟
依赖 Agent 记得调工具
本质是「文字转述」,不是像素级多模态
上游致谢(取长补短)
设计吸收自(MIT / 开源社区):
look4yo/claudecode-vision-mcp — DeepSeek + Claude Code 场景、fallback
mohamedhusseinios/vision-mcp — OCR/UI/图表分层
karlcc/image_mcp — compare_images
相关包
包 | 用途 |
| |
每日项目简报 | |
Prompt 回归测试 |
License
MIT
Available Tools
5 toolscompare_imagesCompare two imagesC
Compare before/after screenshots or UI states. Absorbed pattern from image_mcp.
| Name | Required | Description | Default |
|---|---|---|---|
| source_a | Yes | ||
| source_b | Yes | ||
| task | No |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Local path, http(s) URL, or data:image/... URL | |
| context | No | ||
| question | No | Specific question about the image | |
| mode | No |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Local path, http(s) URL, or data:image/... URL | |
| context | No | ||
| question | No | Specific question about the image |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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.
5 tool updates
v0.2.1- First observed
compare_images - First observed
describe_image - First observed
extract_text - First observed
vision_rules - First observed
vision_status
TDQS
Scored across 5 tools
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.
All tool names follow a consistent verb_noun snake_case pattern (compare_images, describe_image, extract_text, vision_rules, vision_status). Predictable and clear.
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.
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
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
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Create images & video from any MCP agent — 17 models, spend limits, one URL.
Multimodal video analysis MCP — transcription, vision, and OCR for any video URL.
MCP tools for AI agents: render URLs to image/PDF, check link health, convert HTML/CSV/JSON.
Related MCP Servers
- AlicenseAqualityBmaintenanceBridges DeepSeek (text-only) with vision models via MCP, enabling image description and compression using any OpenAI-compatible visual API.3211MIT
- AlicenseAqualityBmaintenanceBridges vision models to text-only coding models using Florence-2, enabling non-vision LLMs to describe images, extract text, and analyze screenshots via MCP tools.6MIT
- AlicenseAqualityBmaintenanceEnables non-multimodal models to see images by providing MCP tools for image understanding and OCR, backed by any OpenAI-compatible vision model.2MIT
- AlicenseNot gradedqualityCmaintenanceAdds vision capabilities to text-only LLMs by integrating external vision models via MCP. It supports OCR, error screenshot reading, UI description, image comparison, and natural-language queries on images.25MIT