目录
功能特性
图像分析
视频理解
简单集成
支持的工具
环境变量配置
安装与使用
使用示例
视觉理解 MCP Server 是智谱为 GLM Coding Plan 用户开发的专属 Local MCP Server，基于模型上下文协议（Model Context Protocol），可为 Claude Code、Cline 等兼容 MCP 的客户端提供图像分析、视频理解等视觉能力。
如需体验 GLM-5.3-Flash 能力，请安装最新版本(>= 0.1.2) 的视觉理解MCP服务器。
老用户可能会使用旧缓存版本，需删除 npx 缓存，或将@z_ai/mcp-server加上@latest标签强制安装最新版本，即@z_ai/mcp-server@latest。
功能特性
图像分析
支持多种图像格式的智能分析和内容理解，让您的 AI Agent 拥有视觉
视频理解
支持本地视频与远端视频的视觉理解
简单集成
一键安装，快速集成到 Claude Code 等 MCP 兼容客户端
支持的工具
该服务器实现了模型上下文协议，可与任何兼容 MCP 的客户端一起使用，模型可根据用户 Prompt 自主调用最匹配的工具，实现在以下类型任务中更精准的效果。目前提供以下工具：
ui_to_artifact- 将 UI 截图转换为代码、提示词、设计规范或自然语言描述，覆盖从前端落地到生成式设计提示的全流程extract_text_from_screenshot- 使用先进的 OCR 能力从截图中提取和识别文字。专门用于代码、终端输出、文档和通用文本的提取diagnose_error_screenshot- 解析错误弹窗、堆栈和日志截图，给出定位与修复建议understand_technical_diagram- 针对架构图、流程图、UML、ER 图等技术图纸生成结构化解读analyze_data_visualization- 阅读仪表盘、统计图表，提炼趋势、异常与业务要点ui_diff_check- 对比两张 UI 截图，识别视觉差异和实现偏差。专门用于 UI 质量保证和设计到实现的验证image_analysis- 通用图像理解能力，适配未被专项工具覆盖的视觉内容video_analysis- 支持 MP4/MOV/M4V(限制本地最大8M) 等格式的视频场景解析，抓取关键帧、事件与要点
环境变量配置
详细配置说明
| 环境变量 | 说明 | 默认值 | 可选值 |
|---|---|---|---|
Z_AI_API_KEY | 智谱 API KEY | 必需配置 | 您的API密钥 |
Z_AI_MODE | 服务平台选择 | ZHIPU | ZHIPU或ZAI |
安装与使用
快速开始
获取 API Key
- 个人版套餐（或领取体验卡）的用户，通过 个人编程套餐 > 套餐概览，新建 API Key
- 团队版套餐的成员，通过 团队编程套餐 > 我的套餐，新建 API Key
安装 MCP 服务器
前提条件：您需要安装 Node.js 18 或更新版本
根据您使用的客户端参考下方选择相应的安装方式
支持的客户端
Claude Code
Cline (VS Code)
OpenCode
Crush
Roo Code, Kilo Code 等其它
在 Claude Code 中使用 GLM Coding Plan 时，模型服务端已内置image_analysis工具，具备图片理解能力，无需安装。如需使用全部视觉工具，再按以下方式安装。
方式一：一键安装命令注意替换里面的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) 执行相同的命令。 若遇到告警 Windows requires ‘cmd /c’ wrapper to execute npx，可以忽略。
方式二：手动配置编辑 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" } } } }使用示例
通过上一步将视觉 MCP 服务器安装到客户端后，您就可以在自己的 Coding 客户端通过对话的方式直接使用MCP了。
比如下面在 Claude Code 中，对话输入hi describe this xx.png，MCP Server 会处理图片并返回描述结果。(前置条件是您的当前目录下有该图片)
除了 Claude Code 之外，直接在客户端粘贴图片无法调用此 MCP Server，客户端默认会将图片转码后直接调用模型接口。最佳实践是将图片放到本地目录，通过对话的方式指定图片名称或路径来调用 Mcp Server。例如:What does demo.png describe?
故障排除在本地命令行直接执行下面的命令，验证其是否能安装到本地，用于排查是否是环境，权限等问题：
Linux/macOS
Windows Cmd
Windows PowerShell
Z_AI_API_KEY=YOUR_API_KEY npx -y @z_ai/mcp-server- 若安装成功，则表示环境正确，问题可能在客户端配置上，请检查客户端的 MCP 配置。
- 若安装失败，请根据错误信息进行排查，建议将错误信息粘贴给大模型进行分析解决。
其它常见问题：
连接失败
API Key 无效
连接超时
相关资源
- 模型上下文协议 (MCP) 官方文档
- Claude Code MCP 配置指南
- MCP 使用额度说明
- 视觉模型介绍
