Skip to main content
视觉理解 MCP Server 是一个基于模型上下文协议 (Model Context Protocol) 的 Z.AI GLM-4.5V 能力实现，为 Claude Code, Cline 等兼容 MCP 的客户端提供智谱的强大能力，包括图像分析、视频理解等功能。
NPM 包地址: @z_ai/mcp-server
前提条件: Node.js >= v18.0.0

​
产品简介

此拥有视觉能力的 Local MCP Server 是智谱为 GLM Coding Plan 用户开发的专属 Server, 让您的 Code Agent 拥有眼睛，视觉理解。
除了 Claude Code 之外，直接在客户端粘贴图片无法调用此 MCP Server，客户端默认会将图片转码后直接调用模型接口。
最佳实践是将图片放到本地目录，通过对话的方式指定图片名称或路径来调用 Mcp Server。
例如: What does demo.png describe?

​
功能特性

图像分析

支持多种图像格式的智能分析和内容理解，让您的 AI Agent 拥有视觉

视频理解

支持本地视频与远端视频的视觉理解

简单集成

一键安装，快速集成到 Claude Code 等 MCP 兼容客户端

​
支持的工具

该服务器实现了模型上下文协议，可与任何兼容 MCP 的客户端一起使用。目前提供以下工具：
  • image_analysis - 分析图像并提供详细描述，支持多种图像格式
  • video_analysis - 分析视频并提供详细描述，支持多种视频格式

​
环境变量配置

​
详细配置说明

环境变量说明默认值可选值
Z_AI_API_KEY智谱 API KEY必需配置您的API密钥
Z_AI_MODE服务平台选择ZHIPUZHIPU 或 ZAI

​
安装与使用

​
快速开始

1

获取 API Key

前往 智谱开放平台 获取您的 API Key
2

安装 MCP 服务器

前提条件：您需要安装 Node.js 18 或更新版本
根据您使用的客户端 参考下方 选择相应的安装方式

​
支持的客户端

  • Claude Code
  • Cline (VS Code)
  • OpenCode
  • Crush
  • Roo Code, Kilo Code 等其它
方式一：一键安装命令注意替换里面的 your_api_key 为您上一步获取到的 API Key
claude mcp add -s user zai-mcp-server --env Z_AI_API_KEY=your_api_key -- npx -y "@z_ai/mcp-server"
若您忘记替换 API Key，重新执行安装命令前需要先卸载旧的此 MCP Server：
claude mcp list
claude mcp remove zai-mcp-server
若您在 Windows 系统的 PowerShell 中执行上述命令时遇到 -y 参数问题，请尝试使用 Windows 命令提示符 (CMD) 执行相同的命令。
方式二：手动配置编辑 Claude Code 的配置文件, 位于用户目录下 .claude.json 的 MCP 部分：
注意替换里面的 your_api_key 为您上一步获取到的 API Key
{
  "mcpServers": {
    "zai-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@z_ai/mcp-server"
      ],
      "env": {
        "Z_AI_API_KEY": "your_api_key",
        "Z_AI_MODE": "ZHIPU"
      }
    }
  }
}

​
使用示例

除了 Claude Code 之外，直接在客户端粘贴图片无法调用此 MCP Server，客户端默认会将图片转码后直接调用模型接口。
最佳实践是将图片放到本地目录，通过对话的方式指定图片名称或路径来调用 Mcp Server。
例如: What does demo.png describe?
通过上一步将视觉MCP服务器安装到客户端后，您就可以在自己的Coding客户端通过对话的方式直接使用MCP了。
比如下面在 Claude Code 中，对话输入 hi describe this xx.png，MCP Server 会处理图片并返回描述结果。(前置条件是您的当前目录下有该图片) Description code

​
MCP 使用额度说明

调用额度如下：
  • Lite 套餐：联网搜索 MCP 和网页读取 MCP 每月合计 1 百次，达到上限后当月无法调用；视觉理解 MCP 共享套餐的 5 小时最大 prompt 资源池，达到上限后会在 5 小时周期后恢复额度。
  • Pro 套餐：联网搜索 MCP 和网页读取 MCP 每月合计 1 千次，达到上限后当月无法调用；视觉理解 MCP 共享套餐的 5 小时最大 prompt 资源池，达到上限后会在 5 小时周期后恢复额度。
  • Max 套餐：联网搜索 MCP 和网页读取 MCP 每月合计 4 千次，达到上限后当月无法调用；视觉理解 MCP 共享套餐的 5 小时最大 prompt 资源池，达到上限后会在 5 小时周期后恢复额度。

​
故障排除

在本地命令行直接执行下面的命令，验证其是否能安装到本地，用于排查是否是环境，权限等问题： 
Z_AI_API_KEY=your_api_key npx -y @z_ai/mcp-server
  • 若安装成功，则表示环境正确，问题可能在客户端配置上，请检查客户端的 MCP 配置。
  • 若安装失败，请根据错误信息进行排查，建议将错误信息粘贴给大模型进行分析解决。
其它常见问题：
问题： MCP 服务器连接失败解决方案：
  1. 检查本地是否存在 Node.js 18 或更新版本
  2. node -v 和 npx -v 查看是否拥有执行环境
  3. 确认环境变量 Z_AI_API_KEY 是否正确配置
问题： 收到 API Key 无效的错误解决方案：
  1. 确认 API Key 是否正确复制
  2. 检查 API Key 是否已激活
  3. 确认选择的平台 (Z_AI_MODE) 与 API Key 匹配
  4. 检查 API Key 是否有足够的余额
问题： MCP 服务器连接超时解决方案：
  1. 检查网络连接
  2. 确认防火墙设置
  3. 尝试切换到不同的平台 (ZHIPU 或 ZAI)
  4. 增加超时时间设置

​
相关资源