给 Hermes Agent 装上慧眼：GLM 视觉 MCP Server 配置指南
给 Hermes Agent 装上慧眼：GLM 视觉 MCP Server 配置指南
青萍叙事前言
Hermes Agent 自带 vision 工具集，能做基本的图像识别。
但面对复杂场景：截图里密密麻麻的报错信息、一张需要逐字提取的表格照片、或者想把 UI 截图直接变成代码，它的能力就有些吃力了。
智谱（Z.AI）推出的 GLM-4.6V 视觉理解 MCP Server 刚好补上了这块短板。
它提供了 8 个专用工具，覆盖图像分析、OCR 文字提取、错误截图诊断、UI 截图转代码等场景，而且接入 Hermes 的门槛很低，改一个配置文件就行。
这篇文章带你从零开始完成配置，4 步搞定。
第一步：获取智谱 API Key
智谱的 API Key 分个人版和团队版两个入口：
- 个人版：打开 bigmodel.cn/coding-plan/personal/overview，登录后在控制台新建 API Key
- 团队版：打开 bigmodel.cn/coding-plan，获取团队套餐对应的 Key
拿到 Key 后先存好，后面配置会用到。
注意：这个 Key 在智谱平台上有多个叫法：
GLM_API_KEY、Z_AI_API_KEY其实是同一个值，只是不同文档用了不同名字。
本文配置中用Z_AI_API_KEY这个字段名。
第二步：全局安装 MCP Server 包
在终端执行：
1 | npm install -g @z_ai/mcp-server@latest |
这条命令把智谱的 MCP Server 包拉到全局环境。
加 @latest 标签是为了确保拿到最新版本。
安装完成后，你可以验证一下包是否就位：
1 | npm list -g @z_ai/mcp-server |
第三步：配置 Hermes 的 config.yaml
这一步是核心操作：把 MCP Server 注册到 Hermes 里。
打开 Hermes 的配置文件：
1 | # 文件路径 |
在 mcp_servers 节点下添加以下内容：
1 | mcp_servers: |
把 your_api_key_here 替换成你在第一步拿到的真实 API Key。
配置字段解释
| 字段 | 作用 |
|---|---|
zai-mcp-server |
自定义的服务器名称，后续验证和调试会用到 |
command: npx |
通过 npx 启动 MCP Server |
args: ["-y", "@z_ai/mcp-server@latest"] |
-y 自动确认安装，@latest 拉最新版 |
env.Z_AI_API_KEY |
你的智谱 API Key，必须显式传入 |
env.Z_AI_MODE |
服务平台标识，智谱用户设为 "ZHIPU" |
重要提醒：
config.yaml是 Hermes 的安全配置文件，Agent 无法通过工具直接修改它。
你需要手动用文本编辑器编辑，或者用 Python 脚本写入。
同时，MCP 环境变量不会继承终端的环境变量，哪怕你在.zshrc里export了 Key，也必须在配置的env字段里再写一遍。
如果你的 config.yaml 里已经有其他 MCP Server，直接在 mcp_servers 下追加即可，不要覆盖已有配置。
第四步：验证连接
配置完成后，跑一条命令测试 MCP Server 是否正常工作：
1 | hermes mcp test zai-mcp-server |
正常情况下，你会看到类似这样的输出：
1 | ✓ Connected in ~1.4s |
连接成功，发现 8 个工具，说明配置没问题，可以开始用了。
如果连接失败，检查这几项：
- API Key 是否正确（没有多余空格、没有漏字符）
- Node.js 版本是否 ≥ v18（智谱官方文档要求）
- 网络是否能访问智谱的 API 端点
你拿到了哪些工具
连接成功后，Hermes Agent 会自动获得以下 8 个视觉理解工具：
| 工具 | 功能 | 典型场景 |
|---|---|---|
image_analysis |
通用图像理解 | 分析任意图片的内容、风格、布局 |
extract_text_from_screenshot |
OCR 文字提取 | 从截图、照片中提取文字 |
diagnose_error_screenshot |
错误截图诊断 | 分析报错截图，给出修复建议 |
understand_technical_diagram |
技术图纸解读 | 理解架构图、流程图、UML 等 |
analyze_data_visualization |
数据可视化分析 | 读取图表中的数据趋势和关键指标 |
ui_diff_check |
UI 截图对比 | 对比两张 UI 截图的差异 |
ui_to_artifact |
UI 转代码/设计规范 | 把 UI 截图转成 HTML/CSS 代码 |
video_analysis |
视频理解 | 分析本地视频内容（≤8MB） |
Agent 会根据你的对话意图自动选择合适的工具，不需要手动指定。
使用方式
配置完成后，使用非常自然：
方式一：直接发图
在 Hermes 对话中发送一张图片，Agent 会自动调用 image_analysis 进行分析。
方式二：文字指令
1 | 请分析这张图片里的文字内容 |
1 | 帮我诊断这个报错截图 |
1 | 把这个 UI 截图转成 HTML 代码 |
Agent 会根据指令调用对应的工具。
方式三：指定本地文件
1 | 请分析 /path/to/screenshot.png |
这是推荐的最佳实践：把图片放到本地目录，通过对话指定路径调用。
原因后面会解释。
实际效果对比
我用一张封面图做了测试（900×500px，橙色背景，上面写着100 篇总结）。
配置前（tesseract OCR）
只能识别出零碎的 4 个字：100 篇总结。其他信息（颜色、布局、图标）一概没有。
配置后（GLM 视觉理解 MCP）
成功返回了完整的图像描述：
- 背景风格：橙色扁平化背景
- 图标元素：文档图标 + 铅笔图标的组合
- 文字内容：100 篇总结居中黑色文字
- 设计判断：识别出这是一个文档总结类的封面设计
从只能抠出几个字到完整理解图片内容和设计意图，提升非常明显。
额度说明
智谱的套餐有不同的额度限制，了解一下避免中途用不了：
| 套餐 | 视觉理解额度 | 其他能力 |
|---|---|---|
| Lite | 视觉理解共享 5 小时最大 prompt 资源池 | — |
| Pro | 同上 | — |
| Max | 同上 | 每月联网搜索 + 网页读取共 4000 次 |
如果你只是个人开发使用，Lite 或 Pro 一般够用。重度用户可以考虑 Max。
注意事项
几个实际使用中容易踩的坑：
1. 粘贴图片的陷阱
如果你在 Claude Code 等客户端里直接粘贴图片，客户端会调用自己的模型接口处理图片，不会走 MCP Server。
正确做法是把图片保存到本地目录，然后在对话中指定路径让 Agent 调用。
2. 环境变量不继承
前面提到过，MCP 进程的环境变量是隔离的。
不要以为终端里 export 了就行，必须在 config.yaml 的 env 字段里显式写入。
3. 版本更新
npm 有缓存机制，如果你需要更新到新版本，可以：
- 配置中始终使用
@latest标签（推荐） - 或者手动清除 npx 缓存后重新安装
4. config.yaml 的安全限制
Hermes 出于安全考虑，不允许 Agent 通过工具直接修改 config.yaml。
所有对这个文件的修改都需要你手动完成。
三分钟上手，体验质的飞跃
整个配置过程其实就三步有实质性操作：拿 Key → 安装包 → 改配置。
验证通过后，Hermes Agent 就多了 8 个视觉理解工具，处理图片相关任务的体验会有质的提升。
如果你在配置过程中遇到问题，优先检查 API Key 和网络连通性，这两个是最常见的原因。
