# 👁️ deepseek-vision-mcp

让**纯文本大语言模型 Agent**（如 DeepSeek 系）获得「眼睛」的 MCP 项目：通过标准 MCP 工具调用智谱 **GLM-4.6V-Flash**（免费视觉模型），完成图片 / 视频 / 文件三种模态的理解，并以纯文本结果回传给 Agent。

<p align="center">
  <a href="https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases"><img src="https://img.shields.io/github/v/release/JunHua-ECJTU/deepseek-vision-mcp" alt="Release"></a>
  <a href="https://github.com/JunHua-ECJTU/deepseek-vision-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/JunHua-ECJTU/deepseek-vision-mcp" alt="License"></a>
  <img src="https://img.shields.io/badge/Python-%3E%3D3.10-blue" alt="Python >= 3.10">
  <a href="https://github.com/JunHua-ECJTU/deepseek-vision-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/JunHua-ECJTU/deepseek-vision-mcp/release.yml" alt="CI"></a>
  <a href="https://github.com/JunHua-ECJTU/deepseek-vision-mcp"><img src="https://img.shields.io/github/stars/JunHua-ECJTU/deepseek-vision-mcp" alt="Stars"></a>
  <img src="https://img.shields.io/badge/Model-GLM--4.6V--Flash-8A2BE2" alt="Model: GLM-4.6V-Flash">
</p>

<p align="center">
  <b>🇨🇳 中文</b> · <a href="./README_EN.md">🇬🇧 English</a>
</p>

> 底层模型：智谱 GLM-4.6V-Flash（免费，128K 上下文，支持思考模式）
> 官方文档：https://docs.bigmodel.cn/cn/guide/models/free/glm-4.6v-flash

## 目录

- [特性](#特性)
- [架构设计](#架构设计)
- [快速开始](#快速开始)
- [安装与部署](#安装与部署)
- [工具与使用示例](#工具与使用示例)
- [测试](#测试)
- [注意事项](#注意事项)
- [许可证](#许可证)

## 特性

- **三模态理解**：图片 / 视频 / 文件（PDF、文本等）一次提问，纯文本返回
- **本地图片免上传**：传本地路径自动转 base64，无需公网 URL；视频/文件模态接受公网 URL
- **思考模式**：可选开启（`thinking=true`），适合需要深度推理的视觉任务
- **健壮性**：3 次指数退避重试（429 / 5xx / 超时）、60s 超时、结构化错误返回（绝不向 Agent 抛未处理异常）
- **标准 MCP（stdio）**：兼容 Claude Code / Cursor / Cline / Continue / Windsurf / Claude Desktop / Reasonix 等任何 MCP 客户端
- **零成本**：基于智谱免费模型，无需充值

## 架构设计

**MCP 执行层 + Skill 决策层**，职责分离：

```
┌─────────────────────────────────────────────────────┐
│  文本模型 Agent（DeepSeek 等）—— 只懂文字            │
│  · 读取 Skill 的业务规则，决定何时调用什么工具        │
└──────────────────────┬──────────────────────────────┘
                       │ MCP 协议（stdio）
┌──────────────────────▼──────────────────────────────┐
│  MCP Server（本仓库，Python）—— 真实执行             │
│  · 读本地文件 / 图片 → base64 编码                    │
│  · 调用智谱 API（认证、重试、超时、异常分类）          │
│  · 提供标准化工具：vision_analyze_image / _video / _file │
└──────────────────────┬──────────────────────────────┘
                       │ HTTPS
┌──────────────────────▼──────────────────────────────┐
│  智谱 GLM-4.6V-Flash API（视觉理解，返回文本）        │
└─────────────────────────────────────────────────────┘
```

| 层 | 职责 | 位置 |
|----|------|------|
| MCP | 真实执行：读文件、base64、调 API、重试、异常捕获、统一错误结构 | `deepseek_vision_mcp/` |
| Skill | 业务规则：何时调用、传什么参数、输出格式、降级策略 | `skills/vision-agent/SKILL.md` |

## 快速开始

**① 安装**

```bash
pip install "deepseek-vision-mcp @ https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases/latest/download/deepseek_vision_mcp-0.2.0-py3-none-any.whl"
```

**② 配置 Key**

```bash
# Windows PowerShell
$env:ZHIPU_API_KEY = "你的Key"
# macOS / Linux
export ZHIPU_API_KEY="你的Key"
```

Key 免费申请：登录[智谱开放平台](https://open.bigmodel.cn) → 个人中心 → [API Keys](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)。

**③ 注册到 Agent**（项目根目录创建 `.mcp.json`）

```json
{
  "mcpServers": {
    "deepseek-vision": {
      "command": "python",
      "args": ["-m", "deepseek_vision_mcp.server"],
      "env": { "ZHIPU_API_KEY": "你的Key" }
    }
  }
}
```

**④ 提问**

```
分析这张图片：https://cdn.bigmodel.cn/static/logo/register.png
```

> 各 Agent 的详细注册方式与常见问题见下文 [安装与部署](#安装与部署)。

## 安装与部署

### 1. 前置条件

| 项目 | 要求 |
|---|---|
| Python | **≥ 3.10**（Windows / macOS / Linux 均可） |
| 智谱 API Key | 免费申请：登录[智谱开放平台](https://open.bigmodel.cn) → 个人中心 → [API Keys](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)（GLM-4.6V-Flash 是免费模型，无需充值） |

检查 Python 版本：

```bash
python --version    # 或 python3 --version
```

> 若未安装 Python：Windows 用 `winget install Python.Python.3.12 --scope user`，macOS 用 `brew install python@3.12`，Linux 用 `apt install python3` 等。

### 2. 安装软件包（四种方式任选其一）

**方式 A：一条命令直接安装（推荐）**

```bash
pip install "deepseek-vision-mcp @ https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases/latest/download/deepseek_vision_mcp-0.2.0-py3-none-any.whl"
```

> 升级版本后，请同步把 URL 中的 `0.2.0` 替换为新版本号。

国内网络下载依赖较慢时加镜像源（wheel 本体仍从 GitHub 拉取，只有依赖走镜像）：

```bash
pip install "deepseek-vision-mcp @ https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases/latest/download/deepseek_vision_mcp-0.2.0-py3-none-any.whl" -i https://pypi.tuna.tsinghua.edu.cn/simple
```

**方式 B：手动下载 wheel 后安装**

1. 打开 Release 页面：https://github.com/JunHua-ECJTU/deepseek-vision-mcp/releases/tag/v0.2.0
2. 在 **Assets** 区下载 `deepseek_vision_mcp-0.2.0-py3-none-any.whl`
3. 本地安装：`pip install deepseek_vision_mcp-0.2.0-py3-none-any.whl`

**方式 C：源码包（sdist，含 skills/ 决策层文件与测试）**

下载 `deepseek_vision_mcp-0.2.0.tar.gz` 后：`pip install deepseek_vision_mcp-0.2.0.tar.gz`

**方式 D：克隆仓库开发安装**

```bash
git clone https://github.com/JunHua-ECJTU/deepseek-vision-mcp.git
cd deepseek-vision-mcp && pip install -e ".[dev]"
```

> 不想污染全局环境时，先建虚拟环境再安装：
> ```bash
> python -m venv .venv
> # Windows：.venv\Scripts\activate    macOS/Linux：source .venv/bin/activate
> pip install ...（上面任一方式）
> ```

**验证安装成功**：

```bash
python -c "from deepseek_vision_mcp.server import main; print('deepseek-vision-mcp OK')"
```

### 3. 配置 API Key（三选一）

**方式 1：环境变量**（临时，当前终端有效）

```bash
# Windows PowerShell
$env:ZHIPU_API_KEY = "你的Key"
# macOS / Linux
export ZHIPU_API_KEY="你的Key"
```

**方式 2：.env 文件**（推荐；MCP server 启动时自动读取当前工作目录的 `.env`）

```bash
echo "ZHIPU_API_KEY=你的Key" > .env
```

**方式 3：MCP 配置文件的 env 字段**（见下文第 4 节各 Agent 模板）

### 4. 注册到你的 Agent（MCP 客户端）

**通用 .mcp.json（Claude Code / Cursor / Cline / Continue / Windsurf 等）**——项目根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "deepseek-vision": {
      "command": "python",
      "args": ["-m", "deepseek_vision_mcp.server"],
      "env": { "ZHIPU_API_KEY": "你的Key" }
    }
  }
}
```

**Claude Desktop**——菜单 → Settings → Developer → Edit Config，写入同样的 JSON 后重启。

**Reasonix**——编辑 `%APPDATA%\reasonix\config.toml`（Windows）或 `~/.reasonix/config.toml`：

```toml
[[plugins]]
name = "deepseek-vision"
command = "python"
args = ["-m", "deepseek_vision_mcp.server"]
env = { ZHIPU_API_KEY = "${ZHIPU_API_KEY}" }
startup_timeout_seconds = 60
call_timeout_seconds = 120
```

并把 Key 放入与 config.toml 同目录的 `.env`（`${VAR}` 由 Reasonix 从环境展开，密钥不入配置文件）；重启或点「刷新插件」。

**其他 MCP 客户端**——任何支持 stdio MCP 的客户端都等价于：

| 字段 | 值 |
|---|---|
| `command` | `python` |
| `args` | `["-m", "deepseek_vision_mcp.server"]` |
| `env` | `ZHIPU_API_KEY=<你的Key>` |

> Windows 下 `python` 不在 PATH 时，把 `command` 换成完整路径，如 `C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\python.exe`。

### 5.（可选）安装 Skill 业务规则层

Skill 指导 Agent「何时调用工具、传什么参数、输出什么格式、失败怎么降级」。从源码包（方式 C）或仓库中取出 `skills/vision-agent/` 目录，复制到你的 Agent 的 skills 目录（各 Agent 约定不同，通常是 `~/.agent/skills/` 或项目 `.agent/skills/`），重启会话生效。

### 6. 验证是否可用

**方法 1：MCP Inspector 官方工具**

```bash
npx @modelcontextprotocol/inspector python -m deepseek_vision_mcp.server
```

应看到 3 个工具：`vision_analyze_image` / `vision_analyze_video` / `vision_analyze_file`。

**方法 2：直接问你的 Agent**

```
分析这张图片：https://cdn.bigmodel.cn/static/logo/register.png
```

或本地图片：

```
帮我看一下 C:\photo\receipt.jpg 里的金额是多少
```

### 7. 常见问题

| 现象 | 处理 |
|---|---|
| 工具返回 `AUTH_ERROR` | Key 未配置或无效，检查第 3 节 |
| 工具返回 `MODALITY_NOT_SUPPORTED` | 视频/文件传了本地路径——视频/文件模态**只接受公网 URL**，先上传到可访问地址 |
| 工具返回 `API_ERROR`（HTTP 429） | 智谱免费模型限流（"访问量过大"），稍后重试或避开高峰 |
| 启动报 `ModuleNotFoundError: mcp` | 依赖未装全，补装：`pip install mcp httpx python-dotenv` |
| Agent 找不到工具 | MCP 注册配置有误；检查 JSON 语法与 `command` 是否可执行 |

> 更多细节（各 Agent 配置、MCP Inspector 用法、故障排查表）见 [docs/DEPLOY.md](docs/DEPLOY.md)。

## 工具与使用示例

| 工具 | 说明 | 关键参数 |
|------|------|----------|
| `vision_analyze_image` | 图片理解（本地路径或 URL） | `source`、`question`、`thinking` |
| `vision_analyze_video` | 视频理解（仅公网 URL） | `source`、`question`、`thinking` |
| `vision_analyze_file` | 文件理解（仅公网 URL，PDF/文本等） | `source`、`question`、`thinking` |

**示例**：让 Agent「描述这张图片」后，工具返回统一 JSON 结构：

```json
{
  "ok": true,
  "content": "图片中是一个深蓝色背景的 Logo，上面有白色文字……",
  "thinking": "",
  "usage": { "prompt_tokens": 123, "completion_tokens": 45 }
}
```

失败时返回 `{"ok": false, "error": {"code": "...", "message": "..."}}`，错误码包括 `FILE_NOT_FOUND`、`UNSUPPORTED_FORMAT`、`AUTH_ERROR`、`API_ERROR`、`TIMEOUT`、`MODALITY_NOT_SUPPORTED`、`INTERNAL` 等。

## 测试

```bash
pytest
```

## 注意事项

- GLM-4.6V-Flash **不支持同时理解多种模态**（图片/视频/文件一次只传一种）——Skill 层已约束
- 视频/文件模态要求可访问的公网 URL（本地文件需先上传到可访问位置）；仅图片支持本地路径
- `.env` 已加入 `.gitignore`，API Key 永不入库
- 本包目前通过 GitHub Release 分发（未发布到 PyPI）

## 许可证

MIT © 2026 Jun Hua