llm-vision-mcp
This server acts as a bridge, giving text-only agents vision by routing images to a multimodal model and returning text descriptions. The analyze_image tool accepts images from local files, URLs, base64 data URIs, clipboard, session-recent images, or raw bytes. It supports predefined tasks (describe, ocr, ui, layout, qa) or free-form prompts, with high/low detail control. Long outputs can be saved to a file, receiving a summary. Compatible with any MCP client (Claude Code, Codex, opencode, Kimi, Cursor, etc.) and configurable via environment variables for major vision providers (GPT-4o, Claude, Gemini, Qwen-VL) with secure API key handling. Optional SSRF guard blocks private URLs.
Integrates with Google Gemini vision models to analyze images, providing detailed descriptions, OCR, UI/layout understanding, and Q&A about visual content.
Integrates with OpenAI-compatible vision APIs to analyze images, providing detailed descriptions, OCR, UI/layout understanding, and Q&A about visual content.
Click on "Deploy 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., "@llm-vision-mcp Describe the UI screenshot in my clipboard."
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.
👁️ mcp-vision-bridge
Give your text-only coding agent eyes.
DeepSeek V4 Flash writes great code — but it can't see the error dialog, the broken UI, or the screenshot you just pasted. This MCP server gives any text-only agent vision by routing images through a multimodal model of your choice.
Works with Claude Code · Codex · opencode · Kimi · PI · Cursor and any MCP client.
Why you need this
Your agent can't see. You paste a screenshot → "I can't see images." You transcribe the error by hand. With this, the agent calls one tool and gets a complete text description — verbatim text, layout, colors, anomalies — and can debug, fix, and explain.
Not a vision model. It's a bridge: it sends your image to a multimodal model you already pay for (mimo, Claude, Gemini, GPT-4o, Qwen-VL…) and returns a detailed description. No images ever enter your agent's context.
Related MCP server: vision-mcp
🚀 Install (pick your agent — that's the whole setup)
Claude Code (one command)
claude plugin marketplace add KuaaMU/agent-plugins
claude plugin install mcp-vision-bridgeThat's it — the plugin bundles the MCP server + vision skill + auto-loop hook. Claude Code will prompt you for your vision endpoint, API key, and model once.
Auto-updating: the MCP server self-syncs the bundled skill + hook into
~/.claude/on startup, so every restart pulls the latest version along with the npm package. SetVISION_NO_SYNC=1to disable auto-sync.
Prefer to manage it in cc-switch (see it + sync to Codex/opencode/Gemini)? Use the installer below instead.
Codex / Reasonix / opencode / Kimi / anything else (one command)
git clone https://github.com/KuaaMU/mcp-vision-bridge && cd mcp-vision-bridge
./install.sh # auto-detects your agent./install.sh claude | reasonix | codex | opencode | kimi if it doesn't auto-detect. You'll be asked for three values: endpoint, key, model.
Reasonix reads the same .mcp.json as Claude Code, so ./install.sh reasonix
(or a manual .mcp.json with the vision server) works — pasted images land in
.reasonix/attachments/ and image="recent" finds them.
Manual (no install script)
Add this as a stdio MCP server in your agent:
{
"command": "npx",
"args": ["-y", "mcp-vision-bridge"],
"env": {
"VISION_OPENAI_BASE_URL": "https://your-endpoint/v1",
"VISION_OPENAI_API_KEY": "sk-your-key",
"VISION_MODEL": "your-vision-model"
}
}Requires Node.js ≥ 18.
🎯 Use
After install, restart your agent, then:
Best way — drag the image file into the chat. Dragging an image file into
any agent (TUI or GUI) inserts its real path, which analyze_image accepts
directly — works identically in Claude Code, Cowork, Codex, opencode, PI, and
more. No clipboard, no paste quirks.
Drag an image file into the input box (or Ctrl+V in Claude Code / Cowork)
Say "看看这个" (or "analyze this", "what's the error?")
Your agent calls
analyze_image→ the vision model describes it in detail
Paste 3 images? The hook reads your session transcript (lossless, multi-image).
image="recent" auto-finds pasted images across Claude Code CLI, Reasonix,
Cowork, and Codex — no clipboard needed. If a desktop GUI doesn't register a
paste (it can fail silently), just drag the file in — a path always works.
The one tool
Agent docs → README_AGENT.md (tool contract, source choice, error handling).
analyze_image(
image = "path | URL | clipboard | recent | session | data:URI", // single, or
["path","path",...] // several in one call
task = "describe | ocr | ui | layout | qa", // or use prompt:
prompt = "What error is on screen?",
detail = "high" | "low",
save_to = "optional file for long output"
)image— local path, http(s) URL,"clipboard","recent"(most recent pasted image in this session),"session"(every image pasted in this session, analyzed in one call), a base64 data URI, or an array of these to analyze multiple images at once (e.g. "compare these two").task— prompt presets for common jobs;ocrasks the vision model to extract text,uispecs a screen, etc. (There's no bundled OCR engine — the model itself does the reading.)prompt— free-form question (overridestask). Pass the user's actual question here — the vision model answers what you ask, so a specific question ("what error is shown?") beats a genericdescribe.
How pasted images are discovered
Pasting an image into a coding agent stores it somewhere. image="recent" /
"session" find it automatically — no clipboard, no manual paths:
Agent | Where pasted images land | Auto-found? |
Claude Code CLI/TUI |
| ✅ |
Reasonix |
| ✅ |
opencode |
| ✅ |
Cowork (Claude-3p desktop) |
| ✅ |
Codex |
| ✅ |
Grok Build |
| ✅ |
Windows clipboard reality: in Explorer, "copy file" (Ctrl+C) puts a file list on the clipboard — not image bytes. So pasting a local image into a CLI only works if you copy the image content (screenshot tool, browser "copy image"). Otherwise just paste the file path —
analyze_imagereads it directly.
Architecture
Three parts that close the loop for a text-only agent:
MCP tool (
analyze_image) — the capability. Sends pixels to your vision model, returns text.Skill (
skills/vision/) — the guidance. Tells the agent when and how to call it.Hook (
UserPromptSubmit) — the automation. Captures a pasted image from the session transcript and triggers the call for you.
Install them all with the plugin (Claude Code) or install.sh (any agent).
How it works
Pure text in, pure text out. The server never interprets the image — it fetches the bytes and lets your vision model do the seeing.
Configuration
All via environment variables (the MCP reads them from your agent's server config).
Variable | When | Example |
| OpenAI-compatible |
|
| OpenAI-compatible |
|
| always |
|
| non-openai |
|
| anthropic |
|
| gemini |
|
| optional |
|
| optional |
|
| optional |
|
Development
npm install
npm run build # tsc → dist/
npm test # vitest
npm run test:e2e # stdio pipeline against a mock providerLayout: src/ (server), skills/vision/ (skill), hooks/ (auto-loop hook),
install.sh (installer), examples/ (per-agent templates).
Release: bump the version in package.json, push, then
git tag vX.Y.Z && git push origin vX.Y.Z — GitHub Actions runs tests and
publishes to npm automatically.
Security
Keys live in env/config only — never in tool arguments.
Optional SSRF guard for URL sources.
Images go only to your configured vision provider.
License
DeepSeek writes the code. mcp-vision-bridge reads the screen.
Available Tools
1 toolanalyze_imageA
Analyze an image using a multimodal model and return a detailed text description. The vision model sees the image; the calling agent is text-only and cannot.
Sources for image (pick one):
"path": absolute or relative path to a local image file (PNG/JPEG/WEBP/GIF)
URL: http(s) URL to an image on the web or a local server
"data:...": base64 data URI, e.g. data:image/png;base64,
"clipboard": read the image currently copied to the system clipboard
"recent": auto-find the most recently pasted image (scans Codex attachments, Grok session images, Claude transcripts)
"session": auto-find images pasted in this session
"raw": the string itself is the literal raw image bytes
Pick task for common jobs (describe | ocr | ui | layout | qa) or pass your own prompt.
detail defaults to "high" for maximum completeness.
Use save_to to write a long description to a file and get back only a path + summary.
Inputs: image (required), task, detail, prompt, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion or overlap. The single tool has a clear and distinct purpose: analyzing images.
The tool name 'analyze_image' follows a clean verb_noun pattern. Since there is only one tool, naming consistency is perfect.
The server has exactly one tool, which feels slightly thin but is reasonable for a highly focused vision analysis server. The tool is comprehensive, handling many tasks through parameters, so the count is not inadequate.
The tool covers a wide range of vision tasks including describe, OCR, UI, layout, and QA, with multiple input sources and output options. There are no obvious gaps for the stated purpose of enabling text-only agents to analyze images.
Maintenance
Related MCP Connectors
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models and 10 tools: up to 4 images per call, SVG vectorization, editing and more. Remote MCP with OAuth, no API keys. Pay per image, no subscription.
Related MCP Servers
- AlicenseAqualityCmaintenanceGives text-only coding agents the ability to 'see' images, videos, and screenshots by routing them to a vision model and returning structured text.827 npm2MIT
- AlicenseAqualityBmaintenanceEnables text-only AI coding agents to analyze images and videos via vision-capable models (Gemini, Grok, OpenRouter), returning text descriptions for reasoning.227 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants without native vision to analyze screenshots, errors, UI designs, and documents through a unified image understanding tool backed by multiple vision model providers. Supports local files, remote URLs, Data URIs, OCR, multi-crop processing, and stdio or HTTP deployment for shared access.512 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants without native vision to analyze screenshots, error messages, UI layouts, and documents through a single image-understanding tool that routes requests to multiple vision LLM providers. It accepts local files, remote URLs, and Data URIs with automatic cropping, compression, and retry handling, and can run over stdio or as a shared HTTP instance.512 npmMIT