> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigmodel.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 视觉理解 MCP

视觉理解 MCP Server 是智谱为 GLM Coding Plan 用户开发的专属 Local MCP Server，基于模型上下文协议（Model Context Protocol）接入 智谱 GLM-4.6V 能力，可为 Claude Code、Cline 等兼容 MCP 的客户端提供图像分析、视频理解等视觉能力。

<Tip>
  如需体验 GLM-4.6V 能力，请安装最新版本(>= 0.1.2) 的视觉理解MCP服务器。\
  老用户可能会使用旧缓存版本，需删除 npx 缓存，或将 `@z_ai/mcp-server` 加上 `@latest` 标签强制安装最新版本，即 `@z_ai/mcp-server@latest`。
</Tip>

## 功能特性

<CardGroup cols={3}>
  <Card title="图像分析" icon={<svg style={{maskImage: "url(https://mintcdn.com/zhipu-ef7018ed/6jZAOYw-eXEZh1pv/resource/icon/image.svg?fit=max&auto=format&n=6jZAOYw-eXEZh1pv&q=85&s=e08359b6e7da6742ec2d4e6e9b7bc438)", maskRepeat: "no-repeat", maskPosition: "center center",}} className={"h-6 w-6 bg-primary dark:bg-primary-light !m-0 shrink-0"}/>}>
    支持多种图像格式的智能分析和内容理解，让您的 AI Agent 拥有视觉
  </Card>

  <Card title="视频理解" icon={<svg style={{maskImage: "url(https://mintcdn.com/zhipu-ef7018ed/AteIdKqxoD35bkVX/resource/icon/video.svg?fit=max&auto=format&n=AteIdKqxoD35bkVX&q=85&s=54282ae2b5141037a874a54cba2bc15d)", maskRepeat: "no-repeat", maskPosition: "center center",}} className={"h-6 w-6 bg-primary dark:bg-primary-light !m-0 shrink-0"}/>}>
    支持本地视频与远端视频的视觉理解
  </Card>

  <Card title="简单集成" icon={<svg style={{maskImage: "url(https://mintcdn.com/zhipu-ef7018ed/6jZAOYw-eXEZh1pv/resource/icon/plug.svg?fit=max&auto=format&n=6jZAOYw-eXEZh1pv&q=85&s=ee8b6362dc2efcf3b5e159abe7f85bc0)", maskRepeat: "no-repeat", maskPosition: "center center",}} className={"h-6 w-6 bg-primary dark:bg-primary-light !m-0 shrink-0"}/>}>
    一键安装，快速集成到 Claude Code 等 MCP 兼容客户端
  </Card>
</CardGroup>

## 支持的工具

该服务器实现了模型上下文协议，可与任何兼容 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` |

## 安装与使用

### 快速开始

<Steps>
  <Step title="获取 API Key">
    * 个人版套餐的用户，通过 [个人编程套餐 > 套餐概览](https://bigmodel.cn/coding-plan/personal/overview)，新建  API Key
    * 团队版套餐的成员，通过 [团队编程套餐 > 我的套餐](http://bigmodel.cn/coding-plan?z_plan=team)，获取  API Key（团队套餐 Key 与平台其他 API Key 不通用，使用团队额度请务必使用团队套餐 Key）
  </Step>

  <Step title="安装 MCP 服务器">
    前提条件：您需要安装 [Node.js 18 或更新版本](https://nodejs.org/en/download/) \
    根据您使用的客户端 **参考下方** 选择相应的安装方式
  </Step>
</Steps>

### 支持的客户端

<Tabs>
  <Tab title="Claude Code">
    <Tip>
      在 Claude Code 中使用 GLM Coding Plan 时，模型服务端已内置 `image_analysis` 工具，具备图片理解能力，无需安装。如需使用[全部视觉工具](/cn/coding-plan/mcp/vision-mcp-server#%E6%94%AF%E6%8C%81%E7%9A%84%E5%B7%A5%E5%85%B7)，再按以下方式安装。
    </Tip>

    **方式一：一键安装命令**

    注意替换里面的 `YOUR_API_KEY` 为您上一步获取到的 API Key

    ```bash theme={null}
    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：

    ```bash theme={null}
    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

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cline (VS Code)">
    在 Cline 扩展设置中添加 MCP 服务器配置：

    注意替换里面的 `YOUR_API_KEY` 为您上一步获取到的 API Key

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="OpenCode">
    在 OpenCode 设置中添加 MCP 服务器配置：

    参考 [OpenCode MCP 文档](https://opencode.ai/docs/mcp-servers)

    注意替换里面的 `YOUR_API_KEY` 为您上一步获取到的 API Key

    ```json theme={null}
    {
        "$schema": "https://opencode.ai/config.json",
        "mcp": {
            "zai-mcp-server": {
                "type": "local",
                "command": ["npx","-y","@z_ai/mcp-server"],
                "environment": {
                    "Z_AI_API_KEY": "YOUR_API_KEY",
                    "Z_AI_MODE": "ZHIPU"
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Crush">
    在 Crush 设置中添加 MCP 服务器配置：

    注意替换里面的 `YOUR_API_KEY` 为您上一步获取到的 API Key

    ```json theme={null}
    {
        "$schema": "https://charm.land/crush.json",
        "mcp": {
            "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"
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Roo Code, Kilo Code 等其它">
    对于 Roo Code, Kilo Code 等其它支持 MCP 协议的客户端，参考以下通用配置：

    注意替换里面的 `YOUR_API_KEY` 为您上一步获取到的 API Key

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 使用示例

通过上一步将视觉 MCP 服务器安装到客户端后，您就可以在自己的 Coding 客户端通过对话的方式直接使用MCP了。\
比如下面在 Claude Code 中，对话输入 `hi describe this xx.png`，MCP Server 会处理图片并返回描述结果。(前置条件是您的当前目录下有该图片)

<Note>
  除了 Claude Code 之外，直接在客户端粘贴图片无法调用此 MCP Server，客户端默认会将图片转码后直接调用模型接口。最佳实践是将图片放到本地目录，通过对话的方式指定图片名称或路径来调用 Mcp Server。例如: `What does demo.png describe?`
</Note>

![Description](https://cdn.bigmodel.cn/markdown/1760501186683image.png?attname=image.png)
![Description](https://cdn.bigmodel.cn/markdown/1782359174332img_v3_02130_be0857a4-7405-40cc-8566-c8f45bbf1f1g.jpg?attname=img_v3_02130_be0857a4-7405-40cc-8566-c8f45bbf1f1g.jpg)

## 故障排除

在本地命令行直接执行下面的命令，验证其是否能安装到本地，用于排查是否是环境，权限等问题：

<CodeGroup>
  ```bash Linux/macOS theme={null}
  Z_AI_API_KEY=YOUR_API_KEY npx -y @z_ai/mcp-server
  ```

  ```cmd Windows Cmd theme={null}
  set Z_AI_API_KEY=YOUR_API_KEY && npx -y @z_ai/mcp-server
  ```

  ```powershell Windows PowerShell theme={null}
  $env:Z_AI_API_KEY="YOUR_API_KEY"; npx -y @z_ai/mcp-server
  ```
</CodeGroup>

* 若安装成功，则表示环境正确，问题可能在客户端配置上，请检查客户端的 MCP 配置。
* 若安装失败，请根据错误信息进行排查，建议将错误信息粘贴给大模型进行分析解决。

其它常见问题：

<AccordionGroup>
  <Accordion title="连接失败">
    **问题：** MCP 服务器连接失败

    **解决方案：**

    1. 检查本地是否存在 Node.js 18 或更新版本
    2. `node -v` 和 `npx -v` 查看是否拥有执行环境
    3. 确认环境变量 `Z_AI_API_KEY` 是否正确配置
  </Accordion>

  <Accordion title="API Key 无效">
    **问题：** 收到 API Key 无效的错误

    **解决方案：**

    1. 确认 API Key 是否正确复制
    2. 检查 API Key 是否已激活
    3. 确认选择的平台 (`Z_AI_MODE`) 与 API Key 匹配
    4. 检查 API Key 是否有足够的余额
  </Accordion>

  <Accordion title="连接超时">
    **问题：** MCP 服务器连接超时

    **解决方案：**

    1. 检查网络连接
    2. 确认防火墙设置
    3. 尝试切换到不同的平台 (`ZHIPU` 或 `ZAI`)
    4. 增加超时时间设置
  </Accordion>
</AccordionGroup>

## 相关资源

* [模型上下文协议 (MCP) 官方文档](https://modelcontextprotocol.io/)
* [Claude Code MCP 配置指南](https://docs.anthropic.com/en/docs/claude-code/mcp)
* [MCP 使用额度说明](https://docs.bigmodel.cn/cn/coding-plan/overview#%E4%B8%93%E5%B1%9E-mcp)
* [视觉模型介绍](/cn/guide/models/vlm/glm-4.6v)