Content
# 🔍 Vision MCP — Multi-Model Visual Bridging
> Give pure text models like DeepSeek "eyes" by connecting to 6 free multi-modal visual APIs via MCP protocol.
[](LICENSE)
[](https://modelcontextprotocol.io)
[](#supported-providers)
## 🎯 Problem Solved
When using pure text models like DeepSeek with Claude Code, the model cannot understand images — screenshots of error messages, UI design drafts, hand-drawn architecture diagrams, and scanned documents are all "invisible".
Vision MCP is an MCP Server that automatically detects image requests and bridges to **6 free visual models**, falling back automatically by priority, converting images to text descriptions, and returning them to the main model.
## ✨ Features
| Feature | Description |
|------|------|
| 🆓 **Completely Free** | All 6 Providers are free, zero cost |
| 🔄 **6-Fold Fallback** | Gemini → Silicon Flow → Zhipu → Moonshot → ModelScope → Intern-AI, automatic switching |
| 🇨🇳 **Domestic Friendly** | 5/6 Providers connect directly from mainland China, no proxy required |
| 💾 **Intelligent Cache** | SHA256 deduplication, avoid repeated analysis of the same image, 7-day automatic expiration |
| 🛠 **7 Dedicated Tools** | General analysis / OCR / comparison / error diagnosis / chart analysis / UI evaluation / status check |
| ⚙️ **Fully Configurable** | JSON configuration file, enable/disable Providers as needed, adjust priority |
| 🚀 **Top 235B Model** | ModelScope Qwen3-VL-235B, InternVL3.5-241B available for free |
## 🚀 Quick Start
### 1. Clone and Install
```bash
git clone https://github.com/YOUR_USERNAME/vision-mcp.git
cd vision-mcp
npm install
```
### 2. Get Free API Keys (choose one or more)
| Provider | Get Address | Free Quota |
|----------|----------|----------|
| Google Gemini | https://aistudio.google.com/apikey | 1500 times/day |
| Silicon Flow | https://siliconflow.cn | Register for quota |
| Zhipu AI | https://open.bigmodel.cn | Permanently free |
| Moonshot | https://platform.moonshot.cn | 3 times/minute |
| ModelScope | https://modelscope.cn | 2000 times/day |
| Intern-AI | https://chat.intern-ai.org.cn | 10 times/minute |
### 3. Configure Claude Code
Create or edit `~/.mcp.json` (or project root directory `.mcp.json`):
```json
{
"mcpServers": {
"vision-mcp": {
"command": "node",
"args": ["/path/to/vision-mcp/index.js"],
"env": {
"GEMINI_API_KEY": "AIza...",
"SILICONFLOW_API_KEY": "sk-...",
"ZHIPU_API_KEY": "xxx...",
"MOONSHOT_API_KEY": "sk-...",
"MODELSCOPE_API_KEY": "ms-...",
"INTERN_AI_API_KEY": "sk-..."
}
}
}
}
```
> 💡 Only configure Providers for which you have obtained keys; those not configured will be skipped automatically.
### 4. Verify
In Claude Code:
```
Check visual service status
```
## 📖 Usage Examples
### General Image Analysis
```
Analyze this screenshot: /path/to/screenshot.png
Look at the layout and color scheme of this design draft
```
### OCR Text Extraction
```
Extract text from this image, output table in Markdown: /path/to/scan.jpg
```
### UI Comparison (Design Draft vs. Implementation)
```
Compare these two screenshots, find differences:
- Design draft: /path/to/design.png
- Implementation: /path/to/actual.png
```
### Error Diagnosis
```
Diagnose this error screenshot: /path/to/error.png
Technical stack is React + Next.js 14
```
### Chart Analysis
```
Analyze component relationships and potential issues in this architecture diagram: /path/to/architecture.png
```
### Batch Analysis (Multiple Screenshots)
```
Analyze all screenshots in this folder, output functional and design report:
/path/to/screenshots/
```
## 🏗 Supported Providers
| # | Provider | Model | Parameters | Domestic | Status |
|---|----------|------|------|:--:|:--:|
| 1 | Google Gemini | gemini-2.5-flash | — | Proxy required | ✅ |
| 2 | Silicon Flow | Qwen3-VL-32B-Instruct | 32B | ✅ | ✅ |
| 3 | Zhipu AI | GLM-4V-Flash | — | ✅ | ✅ |
| 4 | Moonshot | moonshot-v1-8k-vision | — | ✅ | ✅ |
| 5 | ModelScope | Qwen3-VL-235B-A22B | 235B | ✅ | ✅ |
| 6 | Intern-AI | InternVL3.5-241B | 241B | ✅ | ✅ |
**Fallback Priority**: Gemini → Silicon Flow → Zhipu → Moonshot → ModelScope → Intern-AI
## ⚙️ Custom Configuration
Edit `config.json`:
```json5
{
"providers": {
"gemini": {
"enabled": true, // Switch
"model": "gemini-2.5-flash",
"priority": 1 // Smaller is more priority
},
"siliconflow": {
"enabled": true,
"model": "Qwen/Qwen3-VL-32B-Instruct",
"baseURL": "https://api.siliconflow.cn/v1",
"priority": 2
}
// ... Other Providers
},
"cache": {
"enabled": true,
"ttlDays": 7 // Cache for 7 days
},
"tools": {
"analyze_image": { "enabled": true, "maxSizeMB": 20 },
"ocr_text": { "enabled": true, "maxSizeMB": 20 }
// Enable/disable tools as needed
}
}
```
## 📁 Project Structure
```
vision-mcp/
├── index.js # MCP Server main program
├── config.json # Provider and tool configuration
├── SKILL.md # Claude Code Skill definition
├── README.md # This document
├── package.json # Node dependencies
└── .vision-mcp-cache/ # Image analysis cache (created automatically)
```
## 🛠 Available Tools
| Tool | Purpose |
|------|------|
| `analyze_image` | General image analysis — screenshots, photos, design drafts |
| `compare_images` | Compare two images — UI regression, design draft vs. implementation |
| `ocr_text` | Text extraction — scanned documents, tables, handwritten notes |
| `diagnose_error` | Error diagnosis — error screenshots, stack analysis |
| `analyze_diagram` | Chart analysis — architecture diagrams, flowcharts, UML |
| `analyze_ui` | UI evaluation — interface design, usability, accessibility |
| `check_vision` | Status check — view available Providers |
## 🔧 Environment Variables
| Variable | Provider |
|------|----------|
| `GEMINI_API_KEY` | Google Gemini |
| `SILICONFLOW_API_KEY` | Silicon Flow |
| `ZHIPU_API_KEY` | Zhipu AI |
| `MOONSHOT_API_KEY` | Moonshot |
| `MODELSCOPE_API_KEY` | ModelScope |
| `INTERN_AI_API_KEY` | Intern-AI |
| `OPENAI_API_KEY` | OpenAI (paid) |
| `DASHSCOPE_API_KEY` | Alibaba Bailian (paid) |
| `CUSTOM_VISION_KEY` / `CUSTOM_VISION_MODEL` / `CUSTOM_VISION_BASE_URL` | Custom API |
| `VISION_DEBUG` | Enable debug logs |
## ❓ FAQ
**Q: Why not use LiteLLM / OpenRouter?**
A: They are gateways and do not provide visual capabilities themselves. Directly connecting to native APIs is more stable and has lower latency.
**Q: Image size limit?**
A: Default 20MB, adjustable in `config.json` by tool.
**Q: Cache mechanism?**
A: Based on SHA256 hash of `image path + question`, default 7-day TTL. Same image + same question returns cached result directly.
**Q: How to know which Provider is used?**
A: Use `check_vision` to view. Each analysis result also includes time consumption and version information at the bottom.
**Q: Supports URL / clipboard?**
A: Currently supports local file paths and Data URL. HTTP URL recommended to download to local first.
**Q: Can I add my own API?**
A: Yes. Configure any OpenAI-compatible API in `config.json` under the `custom` provider.
## 📄 License
MIT
