# deepseek-vision-mcp

为**没有视觉能力**的大模型（如 DeepSeek 等纯文本模型）补齐图片识别 / OCR 能力的**通用** MCP 服务器。基于 **OpenAI 兼容协议**，一套代码可对接任意支持该协议的多模态厂家（智谱、OpenAI、通义千问、Kimi 等）。

> **解决什么问题**：DeepSeek 等模型"看不见"图片。通过本 MCP 服务器，Claude Code 等 MCP 客户端可以调用**任一家**视觉模型分析图片、提取文字，再把结果以文本形式交给模型——让 DeepSeek 也能"看图"。

---

## ⚠️ 安全警告（必读）

- **API Key 只能放在 `.env` 文件中**，`.env` 已被 `.gitignore` 排除，**永远不会被提交到 git / GitHub**。
- **绝对不要**把 `.env`、或任何包含 Key 的内容复制、提交或公开。
- 本项目开源的是**代码**，密钥由你自己在本地配置。
- 若 Key 意外泄露，请立即到对应厂家平台删除并重新生成，避免产生费用损失。

---

## 功能特性

| 工具 | 说明 |
|---|---|
| `analyze_image(image, prompt)` | 分析 / 描述图片，支持本地路径、URL、base64 |
| `ocr_image(image)` | 提取图片中的全部文字（OCR） |
| `list_models()` | 查看当前配置与常用视觉模型端点 |

- **多厂家通用**：任意 OpenAI 兼容多模态端点，改 3 个环境变量即切换
- 默认使用智谱**免费**模型 `glm-4.6v-flash`（128K 上下文，零成本）
- 支持 jpg / jpeg / png / webp / gif / bmp，单张 < 10MB
- 内置 429 限流指数退避自动重试
- 基于 FastMCP，单文件即可运行

## 支持厂家（改配置即切换）

| 厂家 | VISION_BASE_URL | 示例模型 |
|---|---|---|
| 智谱 AI | `https://open.bigmodel.cn/api/paas/v4` | `glm-4.6v-flash`（免费）/ `glm-4.6v` |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o` / `gpt-4o-mini` |
| 阿里云通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-vl-max` / `qwen-vl-plus` |
| Kimi (Moonshot) | `https://api.moonshot.cn/v1` | `moonshot-v1-vision-preview` / `kimi-latest` |

> 其他支持 OpenAI 兼容接口的多模态厂家均可，按同样方式配置即可。

## 环境要求

- Python 3.10 及以上
- pip（Python 包管理器）

## 安装

```bash
# 1. 获取本项目
git clone https://github.com/<你的GitHub用户名>/deepseek-vision-mcp.git
cd deepseek-vision-mcp

# 2. 安装依赖
pip install fastmcp python-dotenv
```

## 配置 API Key

1. 注册任一家支持视觉模型的平台并获取 Key（如智谱：https://open.bigmodel.cn/ → API Keys → 创建）
2. 复制 `.env.example` 为 `.env`：

```bash
cp .env.example .env
```

3. 编辑 `.env`，填入你的 Key 并选择厂家：

```ini
# 例：智谱（免费）
VISION_API_KEY=你的智谱APIKey
VISION_BASE_URL=https://open.bigmodel.cn/api/paas/v4
VISION_MODEL=glm-4.6v-flash

# 例：OpenAI（改三行即切换）
# VISION_API_KEY=sk-你的OpenAIKey
# VISION_BASE_URL=https://api.openai.com/v1
# VISION_MODEL=gpt-4o-mini
```

完整的多厂家示例见 `.env.example`。

## 注册到 Claude Code

```bash
claude mcp add zhipu-vision -- python D:/你的路径/server.py
```

> **提示**：Windows 下路径含反斜杠可能被 shell 转义，建议使用**正斜杠**路径：
>
> `claude mcp add zhipu-vision -- python D:/claude/zhipu-vision-mcp/server.py`
>
> 默认注册在当前项目作用域；如需所有项目可用，追加参数 `-s user`。

验证注册：

```bash
claude mcp list
```

看到 `zhipu-vision: ... ✔ Connected` 即注册成功。

## 使用

注册并**重启** Claude Code 会话后，直接对话即可（系统会自动调用 MCP 工具）：

```
识别这张图：D:\图片\photo.png
看下这张图里有什么
提取这个截图里的文字
```

也可以显式指定工具：

- 要求分析：`用 analyze_image 分析 D:\图片\photo.png`
- 要求 OCR：`用 ocr_image 提取 D:\截图\code.png 的文字`

### 支持的图片来源

| 类型 | 示例 |
|---|---|
| 本地路径 | `D:\图片\photo.png` |
| 远程 URL | `https://example.com/image.png` |
| base64 数据 | `data:image/png;base64,xxxxx` |

## 独立测试（不通过 MCP）

```bash
python make_test_image.py   # 生成带文字 "TEST 123" 的测试图
python test_server.py       # 调用 analyze_image / ocr_image 验证 API 链路
```

## 常见问题

- **401 错误**：API Key 无效或未在 `.env` 配置，检查后重试。
- **429 错误**：厂家限流，服务器已自动指数退避重试；频繁使用建议换付费模型或提高配额。
- **图片过大**：单张需 < 10MB，超限请先压缩。
- **找不到 MCP 工具**：确认已执行 `claude mcp add ...` 并重启会话。
- **如何切换厂家**：修改 `.env` 中的 `VISION_BASE_URL` 和 `VISION_MODEL`，重启 MCP 服务器。

## License

[MIT](LICENSE)

## 免责声明

本项目仅提供视觉模型调用封装，与 DeepSeek、智谱 AI 等均无官方关联。使用各厂家 API 需遵守其服务条款；请自行妥善保管 API Key。