内容
# 🔍 Vision MCP — 多模型视觉桥接
> 让 DeepSeek 等纯文本模型拥有「眼睛」，通过 MCP 协议桥接到 6 个免费多模态视觉 API。
[](LICENSE)
[](https://modelcontextprotocol.io)
[](#-支持的provider)
## 🎯 解决的问题
Claude Code 使用 DeepSeek 等纯文本模型时，模型无法理解图片 —— 截图的报错、UI 设计稿、手绘架构图、文档扫描件统统「看不见」。
Vision MCP 是一个 MCP Server，自动检测图片请求，桥接到 **6 个免费视觉模型**，按优先级自动 Fallback，将图片转为文字描述后返回给主模型。
## ✨ 特性
| 特性 | 说明 |
|------|------|
| 🆓 **完全免费** | 6 个 Provider 全部免费，零成本 |
| 🔄 **6重Fallback** | Gemini → 硅基 → 智谱 → 月之暗面 → 魔搭 → Intern-AI，自动切换 |
| 🇨🇳 **国内友好** | 5/6 个 Provider 国内直连，无需代理 |
| 💾 **智能缓存** | SHA256 去重，避免重复分析同一张图，7天自动过期 |
| 🛠 **7个专用工具** | 通用分析 / OCR / 对比 / 错误诊断 / 图表分析 / UI评估 / 状态检查 |
| ⚙️ **完全可配置** | JSON 配置文件，按需启用/禁用 Provider，调整优先级 |
| 🚀 **235B顶级模型** | 魔搭 Qwen3-VL-235B、InternVL3.5-241B 免费可用 |
## 🚀 快速开始
### 1. 克隆并安装
```bash
git clone https://github.com/YOUR_USERNAME/vision-mcp.git
cd vision-mcp
npm install
```
### 2. 获取免费 API Key（任选一个即可，推荐多个）
| Provider | 获取地址 | 免费额度 |
|----------|----------|----------|
| Google Gemini | https://aistudio.google.com/apikey | 1500次/天 |
| 硅基流动 | https://siliconflow.cn | 注册送额度 |
| 智谱AI | https://open.bigmodel.cn | 永久免费 |
| 月之暗面 | https://platform.moonshot.cn | 3次/分钟 |
| 魔搭 | https://modelscope.cn | 2000次/天 |
| Intern-AI | https://chat.intern-ai.org.cn | 10次/分钟 |
### 3. 配置 Claude Code
创建或编辑 `~/.mcp.json`（或项目根目录 `.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-..."
}
}
}
}
```
> 💡 只需配置你获取了 Key 的 Provider，未配置的会自动跳过。
### 4. 验证
在 Claude Code 中：
```
检查视觉服务状态
```
## 📖 使用示例
### 通用图片分析
```
分析这张截图: /path/to/screenshot.png
看看这张设计稿的布局和配色
```
### OCR 文字提取
```
从这张图片提取文字，表格用Markdown输出: /path/to/scan.jpg
```
### UI 对比（设计稿 vs 实现）
```
对比这两张截图，找出差异:
- 设计稿: /path/to/design.png
- 实现: /path/to/actual.png
```
### 错误诊断
```
诊断这个错误截图: /path/to/error.png
技术栈是 React + Next.js 14
```
### 图表分析
```
分析这个架构图的组件关系和潜在问题: /path/to/architecture.png
```
### 批量分析（多张截图）
```
分析这个文件夹下的所有截图，输出功能和设计报告:
/path/to/screenshots/
```
## 🏗 支持的 Provider
| # | Provider | 模型 | 参数 | 国内 | 状态 |
|---|----------|------|------|:--:|:--:|
| 1 | Google Gemini | gemini-2.5-flash | — | 需代理 | ✅ |
| 2 | 硅基流动 | Qwen3-VL-32B-Instruct | 32B | ✅ | ✅ |
| 3 | 智谱AI | GLM-4V-Flash | — | ✅ | ✅ |
| 4 | 月之暗面 | moonshot-v1-8k-vision | — | ✅ | ✅ |
| 5 | 魔搭 | Qwen3-VL-235B-A22B | 235B | ✅ | ✅ |
| 6 | Intern-AI | InternVL3.5-241B | 241B | ✅ | ✅ |
**Fallback 优先级**：Gemini → 硅基流动 → 智谱 → 月之暗面 → 魔搭 → Intern-AI
## ⚙️ 自定义配置
编辑 `config.json`：
```json5
{
"providers": {
"gemini": {
"enabled": true, // 开关
"model": "gemini-2.5-flash",
"priority": 1 // 越小越优先
},
"siliconflow": {
"enabled": true,
"model": "Qwen/Qwen3-VL-32B-Instruct",
"baseURL": "https://api.siliconflow.cn/v1",
"priority": 2
}
// ... 其他 Provider
},
"cache": {
"enabled": true,
"ttlDays": 7 // 缓存7天
},
"tools": {
"analyze_image": { "enabled": true, "maxSizeMB": 20 },
"ocr_text": { "enabled": true, "maxSizeMB": 20 }
// 按需开关工具
}
}
```
## 📁 项目结构
```
vision-mcp/
├── index.js # MCP Server 主程序
├── config.json # Provider 和工具配置
├── SKILL.md # Claude Code Skill 定义
├── README.md # 本文档
├── package.json # Node 依赖
└── .vision-mcp-cache/ # 图片分析缓存（自动创建）
```
## 🛠 可用工具
| 工具 | 用途 |
|------|------|
| `analyze_image` | 通用图片分析 — 截图、照片、设计稿 |
| `compare_images` | 两张图对比 — UI回归、设计稿vs实现 |
| `ocr_text` | 文字提取 — 扫描件、表格、手写笔记 |
| `diagnose_error` | 错误诊断 — 报错截图、堆栈分析 |
| `analyze_diagram` | 图表分析 — 架构图、流程图、UML |
| `analyze_ui` | UI评估 — 界面设计、可用性、可访问性 |
| `check_vision` | 状态检查 — 查看可用 Provider |
## 🔧 环境变量
| 变量 | Provider |
|------|----------|
| `GEMINI_API_KEY` | Google Gemini |
| `SILICONFLOW_API_KEY` | 硅基流动 |
| `ZHIPU_API_KEY` | 智谱AI |
| `MOONSHOT_API_KEY` | 月之暗面 |
| `MODELSCOPE_API_KEY` | 魔搭 ModelScope |
| `INTERN_AI_API_KEY` | Intern-AI（书生） |
| `OPENAI_API_KEY` | OpenAI（付费） |
| `DASHSCOPE_API_KEY` | 阿里百炼（付费） |
| `CUSTOM_VISION_KEY` / `CUSTOM_VISION_MODEL` / `CUSTOM_VISION_BASE_URL` | 自定义 API |
| `VISION_DEBUG` | 开启调试日志 |
## ❓ FAQ
**Q: 为什么不用 LiteLLM / OpenRouter？**
A: 它们是网关，本身不提供视觉能力。直接对接原生 API 更稳定、延迟更低。
**Q: 图片大小限制？**
A: 默认 20MB，可在 `config.json` 中按工具调整。
**Q: 缓存机制？**
A: 基于 `图片路径 + 问题` 的 SHA256 哈希，默认 7 天 TTL。相同图片+相同问题直接返回缓存。
**Q: 怎么知道用的是哪个 Provider？**
A: 使用 `check_vision` 查看。每次分析结果底部也有耗时和版本信息。
**Q: 支持 URL / 剪贴板吗？**
A: 当前支持本地文件路径和 Data URL。HTTP URL 建议先下载到本地。
**Q: 能添加自己的 API 吗？**
A: 可以。在 `config.json` 的 `custom` provider 中配置任意 OpenAI 兼容 API。
## 📄 License
MIT
