glm-vision MCP Server

给任意 AI Agent 加上「看图」能力。底层调用智谱完全免费的视觉推理模型， 通过 MCP 协议暴露成标准工具，任何支持 MCP 的客户端都能直接用，零 API 费用。

💡 免费保证：全部使用智谱福利专区的免费模型（GLM-4.6V-Flash / GLM-4.1V-Thinking-Flash / GLM-4V-Flash）， 不包含任何付费模型，长期使用也不会产生费用。

暴露的工具

analyze_image(image_input, question, thinking)

参数	类型	默认值	说明
image_input	string	必填	图片的 http/https URL 或本地文件绝对路径
question	string	请详细描述这张图片	要向模型提的问题
thinking	bool	false	开启思考模式，复杂图表/GUI/推理场景更准

返回：模型输出的文字分析结果。

特性

• 本地图片自动读成裸 base64 传输，不需要图床、不需要公网 URL
• 单图 5MB 上限校验（智谱限制）
• 遇到 429 限流自动退避重试 3 次（1.5s / 3s / 4.5s）
• 仍失败则自动降级：glm-4.6v-flash → glm-4.1v-thinking-flash → glm-4v-flash（全免费）， 降级时会在回答开头标明用了哪个模型

---

部署三步

1. 装依赖

pip install -r requirements.txt

⚠️ 关键坑：mcp 必须装 1.x。最新的 mcp 2.0.0 移除了内置的 mcp.server.fastmcp 模块，装了会直接 ImportError。所以是 pip install "mcp<2"。

⚠️ 另一个坑：不要装 zai 或 zhipuai —— PyPI 上这两个名字都是无关的占位包 （zai 是 Zalando 的、zhipuai 导入名已变）。本 server 走 OpenAI 兼容客户端 直连智谱接口（base_url=https://open.bigmodel.cn/api/paas/v4），只需要 openai 包。

2. 配 API Key

去 bigmodel.cn 手机号注册 → 控制台「API Keys」新建，免费。

Key 有两种给法，环境变量优先级更高：

• 方式 A（推荐）：设环境变量 ZHIPU_API_KEY=你的key
• 方式 B：把 zhipu_key.txt.example 改名为 zhipu_key.txt，里面填上 Key （脚本会自动读同目录下的这个文件）

3. 配到客户端

在客户端的 MCP 配置文件里加一段（路径换成你自己的）：

{
  "mcpServers": {
    "glm-vision": {
      "command": "python",
      "args": ["/绝对路径/到/glm_vision_mcp.py"],
      "env": {
        "ZHIPU_API_KEY": "你的key"
      }
    }
  }
}

各客户端的配置文件位置：

客户端	配置文件路径
WorkBuddy	~/.workbuddy/mcp.json
Claude Desktop (Win)	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop (Mac)	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	项目内 .cursor/mcp.json 或全局 ~/.cursor/mcp.json
Cline / Roo (VSCode)	插件设置里的 cline_mcp_settings.json
Continue	~/.continue/config.json 的 mcpServers 段

command 建议写 Python 解释器的绝对路径（如 D:/python/python.exe）， 避免客户端启动时 PATH 里找不到 python。

配完必须重启客户端 —— MCP 进程只在客户端启动时 spawn 一次，改配置或改代码都不会热重载。

---

验证是否成功

重启客户端后，让 Agent 分析一张图即可：

帮我看看 D:\test.png 这张图里有什么

如果 Agent 说找不到工具，检查：配置文件 JSON 语法、脚本绝对路径是否正确、 是否重启了客户端、客户端是否需要手动「信任/启用」这个 server（WorkBuddy、Cursor 都有这一步）。

常见错误对照

现象	原因
429 / 1305	免费模型限流，不是 Key 无效。server 已自动重试+降级
401	Key 真的无效或没读到
ModuleNotFoundError: mcp.server.fastmcp	装成 mcp 2.x 了，重装 pip install "mcp<2"
未配置智谱 API Key	环境变量和 zhipu_key.txt 都没有
图片过大	单图超 5MB，先压缩

文件清单

文件	必需	说明
glm_vision_mcp.py	✅	server 本体，唯一的核心文件
requirements.txt	建议	依赖清单
zhipu_key.txt	可选	不用环境变量时才需要，内容就是一行 Key
README.md	可选	本文档