Skip to main content
Glama
apsuadwf

zhipu-vision-mcp

by apsuadwf
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

智谱视觉 MCP Server

🌐 为 DeepSeek 等纯文本模型提供视觉能力 —— 通过智谱免费视觉模型"看懂"图片。

License: MIT CI GitHub Release

特性

  • 🆓 完全免费：全部使用智谱免费视觉模型，无需额外付费

  • 🖼️ 本地文件 + 远程 URL：直接传图片路径即可，自动转 Base64 上传

  • 🔄 429 自动降级链：默认模型限流时自动切换下一个模型，同模型内自动重试

  • 🛠️ 三个专用工具：图片分析 / OCR 提取文字 / 双图对比

  • 📦 零配置依赖：只需一个 ZHIPU_API_KEY 环境变量

Related MCP server: api-vision-mcp

原理

用户发图 → MCP 调用 GLM 视觉模型（免费）
        → 返回文字描述
        → DeepSeek / 任意文本模型基于描述推理

快速开始

1. 获取 API Key

访问 智谱开放平台，登录后创建 API Key。

2. 安装

方式 A：本地安装（推荐，一条命令）

git clone https://github.com/apsuadwf/zhipu-vision-mcp.git
cd zhipu-vision-mcp
npm run setup

setup 脚本自动完成：npm link（链接到全局）+ 读取 .env 中的 ZHIPU_API_KEY 配置 Claude MCP。 没有 .env 时先创建（参照 .env.example），或运行后手动补上：

claude mcp add -s user zhipu-vision --env ZHIPU_API_KEY=你的密钥 -- zhipu-vision-mcp

本地安装后 Server 已全局可用（zhipu-vision-mcp 命令），Claude 每次启动零下载、零网络依赖。

方式 B：npx 远程（备选）

claude mcp add -s user zhipu-vision \
  --env ZHIPU_API_KEY=你的密钥 \
  -- npx github:apsuadwf/zhipu-vision-mcp

注：npx 首次运行会从 GitHub 下载源码（有本地缓存），首次较慢；本地安装（方式 A）无此问题。

3. 使用

直接在对话中提及图片，Claude 会自动调用视觉工具分析。也可以手动指定：

"帮我看看这张截图里的报错信息"
"分析这个 UI 设计有什么问题"
"提取这张表格图片里的数据"

其他客户端接入

客户端

配置方式

Claude Desktop / Claude Code

见上方 claude mcp add 命令

Cursor

项目根目录创建 .cursor/mcp.json

Cherry Studio

设置 → MCP 服务 → 添加 → 选择「命令」类型

Continue

~/.continue/config.yaml 的 mcpServers 字段

💡 本地安装（方式 A）后，各客户端配置里的 command 可直接填全局命令 zhipu-vision-mcp（无需 npx、无首次下载）。

// Cursor: .cursor/mcp.json
{
  "mcpServers": {
    "zhipu-vision": {
      "command": "npx",
      "args": ["github:apsuadwf/zhipu-vision-mcp"],
      "env": { "ZHIPU_API_KEY": "你的密钥" }
    }
  }
}
# Continue: config.yaml
mcpServers:
  zhipu-vision:
    command: npx
    args: ["github:apsuadwf/zhipu-vision-mcp"]
    env:
      ZHIPU_API_KEY: 你的密钥

可用工具

工具

功能

analyze_image

分析图片，返回详细文字描述

extract_text_from_image

OCR 提取图片中的文字

compare_images

对比两张图片的差异

可用模型

模型

特点

glm-4.6v-flash ⭐（默认）

最新免费模型，支持本地文件（Base64）和多图

glm-4.1v-thinking-flash

带深度思考，分析更深入

glm-4v-flash

首个免费模型，仅支持 URL 单图

高峰期可能遇到 429 限流，Server 会自动降级到下一个模型，无需手动切换。

环境变量

变量

必填

说明

ZHIPU_API_KEY

✅

智谱开放平台 API Key（获取地址）

限制与行为

项

值

单张图片大小

≤ 5MB

单次请求图片总量

≤ 20MB

请求超时

120 秒

单模型重试

最多 2 次（429 / 5xx / 超时）

429 降级链

glm-4.6v-flash → glm-4.1v-thinking-flash → glm-4v-flash

图片格式

JPG / JPEG / PNG / WebP / GIF / BMP

开发调试

用官方 Inspector 可视化调试工具（无需真实图片）：

# 本地安装后（推荐）
npx @modelcontextprotocol/inspector zhipu-vision-mcp

# 或 npx 远程
npx @modelcontextprotocol/inspector npx github:apsuadwf/zhipu-vision-mcp

# 或本地开发时直接指向源码
npx @modelcontextprotocol/inspector node src/index.mjs

运行测试与代码检查：

npm run check   # lint + test

故障排查

症状

原因与解决

启动时出现 未设置 ZHIPU_API_KEY 警告

未配置 API Key，检查环境变量或客户端配置

API 错误 (HTTP 429)

高峰期限流，Server 已自动重试/降级，稍后重试即可

请求超时（120秒）

网络不稳定或需代理，检查网络后重试

图片过大: X.XMB

单张图片超过 5MB，压缩后再试

不支持的格式

仅支持 JPG / PNG / WebP / GIF / BMP

API 返回了非 JSON 响应

网络或代理干扰，检查代理设置

FAQ

Q：这个 Server 会收费吗？ A：不会。所有模型均为智谱免费模型，只消耗你智谱账号的免费额度。

Q：支持哪些图片格式？ A：JPG / JPEG / PNG / WebP / GIF / BMP，单张不超过 5MB。

Q：只能配合 Claude 使用吗？ A：不是。任何支持 MCP 的客户端都可以接入，见上方「其他客户端接入」。

Q：glm-4v-flash 为什么不支持本地图片？ A：该模型仅接受图片 URL。本地图片请用默认的 glm-4.6v-flash（自动转 Base64）。

Q：429 报错频繁怎么办？ A：Server 会自动降级到备用模型。若仍频繁限流，建议错峰使用或稍后重试。

环境要求

  • Node.js >= 18

  • npm >= 9

项目结构

zhipu-vision-mcp/
├── src/                     # MCP Server 源码
│   ├── index.mjs            # 入口：连接 stdio、信号处理、优雅退出
│   ├── server.mjs           # 工具定义（analyze_image / extract_text_from_image / compare_images）
│   ├── glm.mjs              # GLM API 调用：请求、重试、429 降级链
│   ├── utils.mjs            # 工具函数：图片校验、Base64、响应规范化
│   └── config.mjs           # 配置：模型表、端点、限制常量
├── test/                    # 单元测试（node:test，mock fetch，无需联网）
│   ├── utils.test.mjs
│   └── glm.test.mjs
├── .github/workflows/       # CI（Node 18/20/22 × Ubuntu）
├── .env.example             # 环境变量示例
├── eslint.config.js         # ESLint 配置
└── CHANGELOG.md             # 变更日志

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers