# glm-vision-mcp-server

<div align="center">
  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+" />
  <img src="https://img.shields.io/badge/MCP-%E6%9C%8D%E5%8A%A1%E5%99%A8-7B61FF" alt="MCP 服务器" />
  <img src="https://img.shields.io/badge/ZhipuAI-API-1E90FF" alt="ZhipuAI API" />
  <img src="https://img.shields.io/badge/OpenAI-%E5%85%BC%E5%AE%B9%E6%8E%A5%E5%8F%A3-412991?logo=openai&logoColor=white" alt="OpenAI 兼容接口" />
  <img src="https://img.shields.io/badge/uv-%E5%8C%85%E7%AE%A1%E7%90%86-DEBD95" alt="uv 包管理" />
  <img src="https://img.shields.io/badge/pytest-%E6%B5%8B%E8%AF%95-0A9EDC?logo=pytest&logoColor=white" alt="pytest 测试" />
  <br>
  <img src="https://img.shields.io/badge/AI-%E8%A7%86%E8%A7%89%E7%90%86%E8%A7%A3-FF6B6B" alt="AI 视觉理解" />
  <img src="https://img.shields.io/badge/Agent-%E5%B7%A5%E5%85%B7%E8%B0%83%E7%94%A8-4D96FF" alt="Agent 工具调用" />
  <img src="https://img.shields.io/badge/%E8%B4%B4%E5%9B%BE%E5%8D%B3%E7%94%A8-%E9%9B%B6%E7%A1%AE%E8%AE%A4-FFD93D" alt="贴图即用 零确认" />
  <img src="https://img.shields.io/badge/Claude_Code-Skill-D97757?logo=anthropic&logoColor=white" alt="Claude Code Skill" />
</div>

<div align="center">
  <img src="image/introduce.png" alt="项目介绍" width="80%" />
</div>

基于智谱免费视觉模型 **glm-4.6v-flash** 的 MCP 服务器：理解本地图片或网络图片，返回中文描述或回答问题。

配套 Skill：`~/.claude/skills/glm-vision/SKILL.md`（贴图自动触发）。

## 效果展示

**测试 1：GitHub 项目页面识别**（左：输入图 → 右：GLM 识别结果）

| 输入 | 识别结果 |
|------|---------|
| <img src="image/test-1.png" width="320" alt="测试 1 输入" /> | <img src="image/test-1-result.png" width="320" alt="测试 1 结果" /> |

**测试 2：音乐播放器界面识别**（左：输入图 → 右：GLM 识别结果）

| 输入 | 识别结果 |
|------|---------|
| <img src="image/test-2.png" width="320" alt="测试 2 输入" /> | <img src="image/test-2-result.png" width="320" alt="测试 2 结果" /> |

## 快速开始

> 仓库内已含 Skill 副本（`.claude/skills/glm-vision/SKILL.md`），修改后需同步复制到用户目录才生效。

```bash
# 1. 安装依赖（将下方路径替换为你实际的安装目录）
cd C:/Users/ASUS/.claude/mcp-servers/glm-vision-mcp-server
uv sync

# 2. 全局注册 MCP（stdio，--scope user 使其在任何项目可用）
claude mcp add vision --scope user --env ZHIPUAI_API_KEY=<你的key> -- uv run --directory C:/Users/ASUS/.claude/mcp-servers/glm-vision-mcp-server glm-vision-mcp

# 3. 安装 Skill（贴图自动触发，任何项目可用；已装过可跳过）
mkdir -p ~/.claude/skills/glm-vision
cp .claude/skills/glm-vision/SKILL.md ~/.claude/skills/glm-vision/SKILL.md

# 4. 重启 Claude Code 会话使 MCP 与 Skill 生效
```

API key 获取：https://open.bigmodel.cn/ （注册后「API Keys」页面创建，模型 glm-4.6v-flash 免费）。

## 工具

| 工具 | 参数 | 说明 |
|------|------|------|
| `understand_image` | `images`（必填，1 张或多张，本地路径或 http(s) URL）、`question`（可选） | 理解图片；单图自动描述、多图对比分析；传入问题则回答 |

## 隐私声明

⚠️ 调用本工具时，**图片内容（本地图片 base64 编码或 URL）会发送至智谱 AI 的 API**（open.bigmodel.cn，国内服务器）用于视觉理解。请勿向本工具传入包含敏感信息的截图（账号密码、身份证、聊天记录等）。如需自托管，请自行更换模型服务商（见「更换底层视觉模型」）。

## 开发

```bash
uv run pytest -v          # 单元测试（mock 网络）
```

## 配置

- `ZHIPUAI_API_KEY`：智谱 API key（环境变量，勿硬编码）
- `GLM_VISION_MODEL`：底层视觉模型 ID（可选，默认 `glm-4.6v-flash`）
- 图片限制：本地文件最大 10MB

## 更换底层视觉模型

**原因**：本服务器通过智谱的 **OpenAI 兼容接口**调用模型——鉴权方式、请求格式（content 数组、image_url/base64 传输）、响应结构对所有 glm 系列模型完全一致，**底层模型只由请求中的 `model` 字段决定**。因此更换模型 ID 即可无痛切换视觉模型，代码、Skill、MCP 注册均无需改动。

**用法**（设置环境变量 `GLM_VISION_MODEL` 即可）：

```bash
# 免费版（默认值，不设置时生效）
export GLM_VISION_MODEL=glm-4.6v-flash

# 付费版 glm-4.6v（访问更稳定、限流更少，适合生产使用）
export GLM_VISION_MODEL=glm-4.6v
```

已在 `claude mcp add` 注册过的场景，重新注册并把模型带入 MCP 环境变量：

```bash
claude mcp add vision --scope user \
  --env ZHIPUAI_API_KEY=<你的key> \
  --env GLM_VISION_MODEL=glm-4.6v \
  -- uv run --directory C:/Users/ASUS/.claude/mcp-servers/glm-vision-mcp-server glm-vision-mcp
```

或直接改代码中 `glm_client.py` 的 `DEFAULT_MODEL` 常量（改后需重装/重启生效）。

## 常见问题

> [!IMPORTANT]
> **免费模型会间歇性限流（HTTP 429）**：提示"该模型当前访问量过大，请您稍后再试"是智谱免费模型（glm-4.6v-flash）的时段性共享配额限制，**不是代码或配置问题**。处理方式：
> 1. **稍后重试**：等待 15 秒以上再次调用（限流是时段性的，低谷时段即恢复，通常重试 1-2 次即可）
> 2. **切换付费模型**：设置 `GLM_VISION_MODEL=glm-4.6v` 绕过免费配额，访问更稳定（见「更换底层视觉模型」）

> [!NOTE]
> **修改工具代码后需退出并重新启动 Claude Code 才会生效**：MCP 服务器进程在会话启动时加载，会话期间运行的始终是启动时的代码版本。改动 `glm_client.py` / `server.py` / Skill 后，需**退出当前 Claude Code 会话并重新启动**，工具才会运行新代码；`claude mcp list` 可查看服务器连接状态。