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），修改后需同步复制到用户目录才生效。

# 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，国内服务器）用于视觉理解。请勿向本工具传入包含敏感信息的截图（账号密码、身份证、聊天记录等）。如需自托管，请自行更换模型服务商（见「更换底层视觉模型」）。

开发

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 即可）：

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

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

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

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 可查看服务器连接状态。