# glm-vision-mcp

封装智谱 **GLM-4.6V-Flash**（免费视觉模型）的 MCP 服务器，向任意 MCP 客户端暴露一个 `analyze_image` 工具，支持单图/多图分析、OCR、多图对比。

## 特性

| 能力 | 说明 |
|---|---|
| 图片分析 | 本地路径 / http(s) URL / base64 data URI 均可，自动转 data URI |
| 多图对比 | 多张图片一次传入，按 prompt 对比分析 |
| 限流韧性 | 429 / 1302 / 1305 指数退避重试 → 多 Key 轮询 → 降级备用模型 `glm-4.1v-thinking-flash` |
| 配置自查 | `check_config` 工具检查 Key/模型/端点，不泄露 Key |

## 环境要求

- Python >= 3.10
- 智谱开放平台 API Key（<https://open.bigmodel.cn/usercenter/apikeys>），`glm-4.6v-flash` 免费
- 想进一步降低限流概率，可注册多个账号各取一个 Key，配置时用英文逗号分隔

## 安装

```powershell
cd glm-vision-mcp
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```

## 启动

```powershell
# stdio 模式（MCP 客户端默认方式）
$env:ZHIPU_API_KEY = "你的Key"
.venv\Scripts\python server.py

# SSE 调试模式（无鉴权，仅限本机）
.venv\Scripts\python server.py --sse 8090
```

## 客户端配置

### Codex（`~/.codex/config.toml`）

```toml
[mcp_servers.glm-vision]
command = "C:\\绝对路径\\glm-vision-mcp\\.venv\\Scripts\\python.exe"
args = ["C:\\绝对路径\\glm-vision-mcp\\server.py"]

[mcp_servers.glm-vision.env]
ZHIPU_API_KEY = "你的Key"
# GLM_VISION_MODELS = "glm-4.6v-flash"
# GLM_API_BASE = "https://open.bigmodel.cn/api/paas/v4/chat/completions"
```

### Claude Desktop（`claude_desktop_config.json`）

```json
{
  "mcpServers": {
    "glm-vision": {
      "command": "C:\\绝对路径\\glm-vision-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\绝对路径\\glm-vision-mcp\\server.py"],
      "env": { "ZHIPU_API_KEY": "你的Key" }
    }
  }
}
```

## 工具接口

`analyze_image(images, prompt, temperature, max_tokens, thinking)`

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `images` | string[] | 是 | 本地路径 / http(s) URL / data URI |
| `prompt` | string | 否 | 分析要求，默认“请详细描述这张图片的内容” |
| `temperature` | number | 否 | 0.0~1.0，默认 0.7 |
| `max_tokens` | integer | 否 | 最大输出 token，默认 2048 |
| `thinking` | boolean | 否 | 深度思考模式，默认 false |

## 环境变量

| 变量 | 必填 | 说明 |
|---|---|---|
| `ZHIPU_API_KEY` | 是 | 智谱 API Key，逗号分隔支持多 Key 轮询 |
| `GLM_VISION_MODELS` | 否 | 模型优先级，逗号分隔，默认 `glm-4.6v-flash,glm-4.1v-thinking-flash` |
| `GLM_API_BASE` | 否 | 覆盖 API 端点 |

## 注意事项

- 本地图片单张 ≤ 10MB，支持 jpg/jpeg/png/webp/gif/bmp
- 免费模型高峰期可能限流，全部 Key + 全部模型都限流时才报错，稍等 15~30 秒错峰重试
- 401/400 等非限流错误不降级不重试，直接返回，便于定位配置问题

## 验证

```powershell
# 离线检查（不联网）
.venv\Scripts\python test_smoke.py

# 联网冒烟：MCP 握手 + analyze_image 真实调用
$env:ZHIPU_API_KEY = "你的Key"
.venv\Scripts\python test_smoke.py --live
```