Vision MCP
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., "@Vision MCP OCR the text in ~/Desktop/receipt.png"
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 MCP
The Universal Vision-Language Model MCP Server — Image Understanding & OCR for Any MCP Client
English | 中文 | 日本語 | Deutsch | Changelog
Vision MCP is a universal MCP server that plugs any OpenAI-compatible vision-language model into any MCP client — Claude Code, Reasonix, Cursor, Windsurf, VS Code and more. It exposes two tools: image understanding (describe & Q&A) and OCR (text extraction). Your images never leave your machine.
It is not tied to any model vendor: point it at local Ollama, vLLM, LM Studio, or any remote OpenAI-compatible endpoint — just change configuration, not code.
✨ Highlights
🧠 Model-agnostic — Works with any vision model exposing an OpenAI-compatible API (
qwen2.5vl,llama3.2-vision,minicpm-v, GPT-4o, Gemini…), plus Ollama's native API forkeep_aliveresidency🔌 Client-agnostic — A single server, usable from any MCP client via stdio
📦 Zero-dependency distribution — Ship a single
vision-mcp.exe(Node SEA); recipients need no Node.js, no npm, no Python🖼️ Multi-image — Pass multiple images in one call natively
🔒 Privacy-first — 100% local inference; images never leave the machine (unless you point it at a remote endpoint)
🧭 Smart path handling — Absolute, relative, and
~paths; clear Chinese/English error messages⚙️ Fully configurable — Endpoint, model name, API format, keep-alive and timeout via environment variables
Related MCP server: vision-bridge-mcp
🏗️ Architecture
┌──────────────┐ MCP stdio ┌────────────────────┐ HTTP ┌───────────────────────┐
│ Any MCP │ ─────────────→ │ vision-mcp server │ ──────→ │ Vision backend │
│ client │ ←───────────── │ (Node/TS or exe) │ ←────── │ Ollama | vLLM | ... │
└──────────────┘ text result └────────────────────┘ └───────────────────────┘The server is a thin, stateless bridge: it receives image paths from the MCP client, base64-encodes them, forwards them to the vision backend, and returns the model's text answer.
🛠️ Tools
Tool | Description | Arguments |
| Image understanding / visual Q&A |
|
| Extract all text from images, line-preserved |
|
🚀 Quick Start
1. Run a vision backend (e.g. Ollama)
ollama pull qwen2.5vl:3b
ollama serveVerify: curl http://localhost:11434/api/tags should list your model.
2. Get the server
Option A — Single-file executable (no runtime needed):
Download vision-mcp.exe from the Releases page.
Option B — Run from source:
npm install
npm run build3. Register in your MCP client
Create/merge .mcp.json in your project root (or ~/.claude/.mcp.json for Claude Code globally):
{
"mcpServers": {
"vision-mcp": {
"command": "/path/to/vision-mcp.exe",
"args": []
}
}
}Running from source? Use
"command": "node", "args": ["/path/to/dist/server.cjs"].
4. Use it
「Use vision-mcp to look at ./screenshot.png and describe it」
「OCR the text in ./doc.jpg」⚙️ Configuration
All settings are optional environment variables, passed via the env field in .mcp.json:
Variable | Default | Description |
|
| API format: |
|
| Backend address. |
|
| Model name |
|
| Model residency (Ollama mode only); |
|
| Per-call timeout (covers cold-start model load) |
Switching backends (example: vLLM)
{
"mcpServers": {
"vision-mcp": {
"command": "/path/to/vision-mcp.exe",
"args": [],
"env": {
"VLM_API_MODE": "openai",
"VLM_BASE_URL": "http://192.168.1.10:8000/v1",
"VLM_MODEL": "Qwen/Qwen2.5-VL-3B-Instruct"
}
}
}
}That's it — no code changes, no rebuild when switching providers.
📦 Distribution to Others
Build the single-file executable:
npm run build:exe # outputs dist/vision-mcp.exe (~89 MB)Recipients only need to:
Have their own vision backend (Ollama + model, or set
VLM_BASE_URLto a shared/remote service)Register the exe in any MCP client — no Node, no Python
❓ FAQ
Because the server intentionally exposes exactly two tools: describe_image (image understanding) and ocr_image (OCR). The executable path shown next to the server is the server program itself, not a third tool.
The model is loaded on first use (a few seconds to tens of seconds). Set VLM_KEEP_ALIVE=30m (default) so the model stays resident — subsequent calls return in under a second.
The config is fine; the vision backend is down. Start it: ollama serve, and verify with curl http://localhost:11434/api/tags.
The SEA-built exe embeds your bundle into a copy of node.exe, which invalidates the original Microsoft signature and can trigger false positives. Alternative: build a native binary with Bun: bun build --compile src/server.ts --outfile dist/vision-mcp.exe.
describe_image/ocr_image require a vision (multimodal) model. A text-only model will not read images.
🧑💻 Development
npm install # install dependencies
npm run build # esbuild bundle → dist/server.cjs
npm test # end-to-end test against a real backend (official MCP client over stdio)
npm run build:exe # package single-file executable (Node SEA)End-to-end tests connect through the official MCP SDK client and exercise both tools, multi-image input, and error paths.
📁 Project Structure
├── src/
│ └── server.ts # MCP server source (TypeScript)
├── scripts/
│ ├── test-client.mjs # End-to-end test (official MCP client)
│ └── build-sea.mjs # Single-file executable builder
├── package.json # Build/test/package scripts
└── .mcp.json # Example registration config🤝 Contributing
Issues and pull requests are welcome! For new features, please open an issue to discuss before submitting a PR.
Run
npm run buildto ensure the TypeScript compilesRun
npm testto ensure existing behavior is preservedKeep changes focused and documented
📄 License
MIT © Ameng
Available Tools
2 toolsdescribe_imageA
对一张或多张图片进行视觉理解(识图):可指定任意问题,如描述内容、识别物体、分析图表、理解截图等
Inputs: image_paths (required), question.
ocr_imageA
提取一张或多张图片中的所有文字(OCR),按原始排版分行输出
Inputs: image_paths (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clear but slightly overlapping purposes: describe_image offers general visual understanding, while ocr_image specifically extracts text. An agent could theoretically use describe_image for text extraction, but the OCR tool is more direct and precise for that task.
Both tools follow a consistent verb_noun pattern (describe_image, ocr_image), making the tool names predictable and easy to select.
With only 2 tools, the server feels minimal, but it covers the essential tasks of visual understanding and OCR. It's borderline but not unreasonable for a purpose-built vision server.
The two tools cover the core needs of image understanding and text extraction, and describe_image is versatile enough to handle many query types. Minor gaps exist, such as no dedicated tools for image comparison or object detection, but these can be handled through describe_image.
Maintenance
Related MCP Connectors
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
Related MCP Servers
- AlicenseAqualityCmaintenanceGive MCP-compatible AI agents image analysis, metadata inspection, cropping, OCR, and image comparison through any OpenAI-compatible vision model.6MIT
- AlicenseAqualityDmaintenanceEnables non-multimodal models to see images by providing MCP tools for image understanding and OCR, backed by any OpenAI-compatible vision model.2MIT
- AlicenseAqualityDmaintenanceProvides image recognition capabilities to MCP clients by integrating with OpenAI-compatible vision models, supporting local images, URLs, multi-image comparison, and model listing.4MIT
- AlicenseAqualityCmaintenanceOpenAI-compatible vision recognition MCP server that lets MCP clients see images by routing them to any OpenAI-compatible vision model.1MIT