# Glm-Vision-Mcp —— 智谱视觉识别 MCP 插件

一个本地 [MCP](https://modelcontextprotocol.io) Server，为**无法直接看图**的纯文本大模型（如 DeepSeek）补足图片识别能力。

把一张图片交给**智谱免费视觉模型**识别，并把文字描述返回给调用方——让你的纯文本模型也能"看"到图片内容。

> 支持 Reasonix 等任意 MCP 客户端，也可直接作为标准 stdio MCP Server 使用。

---

## ✨ 特性

- 🖼️ **三种图片输入**：本地文件路径 / 公开 URL / base64 数据
- 🔁 **多模型自动降级**：`glm-4.6v-flash → glm-4.1v-thinking-flash → glm-4v-flash`，遇限流自动切换，无需手动干预
- 💰 **全免费**：三款均为智谱长期免费 Flash 视觉模型
- 🔑 **Key 与代码分离**：API Key 只存在本机 `.env`，绝不进入 Git 仓库
- 🛠️ **一键安装**：`install.py` 自动建环境、装依赖、生成配置，跨平台（Windows/macOS/Linux）
- 🔌 **零额外依赖**：除 MCP SDK 外只用 Python 标准库发请求

---

## 🔧 工作原理

```
你发图片
   │  (MCP stdio)
   ▼
glm_vision_server.py
   │  读取图片（本地文件 / URL / base64 → base64 data URL）
   ▼
智谱视觉模型（按降级队列逐个尝试）
   │  glm-4.6v-flash ──失败──▶ glm-4.1v-thinking-flash ──失败──▶ glm-4v-flash
   ▼
返回图片文字描述 [vision-model: 实际模型]
   │  (纯文本)
   ▼
你当前使用的文本模型（如 DeepSeek）基于描述继续回答
```

---

## 🚀 快速开始（三步）

### 前置要求

- **Python 3.10+**（[下载](https://www.python.org/downloads/)）
- 一个**智谱开放平台 API Key**（免费注册：<https://open.bigmodel.cn>，注册后到「API 密钥」页面创建）

### 第 1 步 · 获取代码

在命令行执行（把下面的地址照抄即可）：

```bash
git clone https://github.com/cfj3191449485-pixel/Glm-Vision-Mcp.git
cd Glm-Vision-Mcp
```

> 已经是本项目作者、或本机已有这份代码的，可以**跳过本步**，直接进第 2 步。

### 第 2 步 · 一键安装

在命令行执行：

```bash
python install.py
```

脚本会自动完成：检查 Python 版本 → 创建 `.venv` → 安装 `mcp` 依赖 → 生成 `.mcp.json`（自动指向你本机的绝对路径）→ 从 `.env.example` 复制出 `.env`。

### 第 3 步 · 填写 API Key（用编辑器改文件，**不是在终端敲命令**）

用**记事本 / VS Code 等文本编辑器**打开项目根目录里的 `.env` 文件，把那一行里等号后面的内容换成**你自己的** key（保留 `ZHIPU_API_KEY=` 这几个字，只换后面的值）：

```
ZHIPU_API_KEY=你自己的智谱key
```

保存后关闭即可。`.env` 已被 `.gitignore` 忽略，不会被提交到 Git；每个人各自填自己的 key 即可。

### 第 4 步 · 重启客户端

重启 Reasonix（或你的 MCP 客户端），它会读取 `.mcp.json` 并自动拉起 `glm-vision` server。之后在对话中发送图片，模型即可自动调用 `describe_image` 识别。

---

## 🖐️ 手动安装（不用脚本）

如果你不想跑脚本，手动三步：

```bash
# 1. 创建虚拟环境并安装依赖
python -m venv .venv
# Windows:
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux:
.venv/bin/pip install -r requirements.txt

# 2. 配置 key
cp .env.example .env   # Windows 用 copy .env.example .env
# 编辑 .env，填入 ZHIPU_API_KEY

# 3. 在项目根目录新建 .mcp.json（把 command/args 换成你机器的实际路径）
```

`.mcp.json` 模板（把 `<项目绝对路径>` 替换成真实路径）：

```json
{
  "mcpServers": {
    "glm-vision": {
      "command": "<项目绝对路径>/.venv/Scripts/python.exe",
      "args": ["<项目绝对路径>/glm_vision_server.py"],
      "env": {
        "ZHIPU_API_KEY": "${ZHIPU_API_KEY}",
        "ZHIPU_VISION_MODELS": "glm-4.6v-flash,glm-4.1v-thinking-flash,glm-4v-flash"
      },
      "type": "stdio",
      "auto_start": true
    }
  }
}
```

> macOS/Linux 下 `command` 是 `<项目绝对路径>/.venv/bin/python`。

---

## ⚙️ 配置项（`.env`）

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `ZHIPU_API_KEY` | （必填） | 智谱开放平台 API Key |
| `ZHIPU_VISION_MODELS` | `glm-4.6v-flash,glm-4.1v-thinking-flash,glm-4v-flash` | 降级队列，逗号分隔，按能力从强到弱 |
| `ZHIPU_VISION_MODEL` | （可选，兼容） | 若只填此项，则只用该单一模型、不降级 |
| `ZHIPU_API_BASE` | `https://open.bigmodel.cn/api/paas/v4` | 接口基地址，一般无需改 |

Key 读取优先级（从高到低）：命令行参数 `--api-key` → 环境变量 `ZHIPU_API_KEY` → `.env` 文件。

---

## 🛠️ 工具参数

server 暴露一个工具 `describe_image`：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `image_path` | 三选一 | 本地图片文件路径 |
| `image_url` | 三选一 | 可公开访问的图片 URL |
| `image_base64` | 三选一 | 图片 base64，或完整 `data:` URL |
| `prompt` | 否 | 识别指令，默认"详细描述图片内容" |
| `max_tokens` | 否 | 生成上限，默认 1024 |
| `models` | 否 | 本次调用的降级队列（逗号分隔），临时覆盖环境配置 |

返回文本自动带 `[vision-model: 模型名]` 前缀，方便排查实际命中的模型。

---

## ❓ 常见问题

**Q：为什么用三个模型、还要降级？**
智谱免费 Flash 模型限 1 并发，高峰期可能返回 `429`（限流）或 `5xx`。降级队列会在失败时自动尝试下一个模型，提高成功率、无需手动切换。三款都是免费模型，降级不增加费用。

**Q：鉴权失败（401/403）会怎样？**
不会降级，直接报错提示检查 API Key——避免用错 key 时反复空耗。

**Q：图片会不会泄露？**
图片会通过**你自己的 API Key** 发送到智谱服务器处理，与本项目无关。请勿上传敏感图片。

**Q：macOS/Linux 能用吗？**
能。`install.py` 已处理不同平台的 venv 路径差异；手动安装时把 `command` 换成 `.venv/bin/python` 即可。

**Q：能否换成其他视觉模型 / 模型供应商？**
当前实现对接智谱 OpenAI 兼容接口（`open.bigmodel.cn`）。若要接千问 Qwen-VL 等，改 `ZHIPU_API_BASE` 和模型名通常即可，兼容 OpenAI chat/completions 格式的供应商基本可直接复用。

---

## 📄 许可与免责声明

- 本项目仅作学习与个人使用参考，不提供任何担保。
- 模型能力、免费额度、限流策略以智谱开放平台官方最新公告为准。