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

一个本地 MCP 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+（下载）
• 一个智谱开放平台 API Key（免费注册：https://open.bigmodel.cn，注册后到「API 密钥」页面创建）

第 1 步 · 获取代码

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

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

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

第 2 步 · 一键安装

在命令行执行：

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 识别。

---

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

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

# 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 模板（把 <项目绝对路径> 替换成真实路径）：

{
  "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 格式的供应商基本可直接复用。

---

📄 许可与免责声明

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