English | 简体中文

---

GLM-4.6V-Flash MCP Server：给"只会读字"的大模型装上"眼睛"

一个基于智谱开放平台 HTTP API 的 MCP 服务器。它把 GLM-4.6V-Flash（智谱开放平台的免费多模态视觉模型）封装成标准 MCP 工具，让 Codex、Cursor、Claude Desktop 等大模型客户端获得"看图、看视频、读文件"的能力，从而让原本只会处理文字（单语言）的大模型也能实现多模态效果。

目录

• 这是什么？为什么要做这个项目？
• MCP 是什么？
• 工作原理：它是怎么让大模型"看见"的？
• 核心特性
• 底层 API 说明
• 提供的 MCP 工具
• 快速开始
• 接入客户端
• 在 Codex 桌面版中使用（资源方式）
• 手动调用示例
• 注意事项
• 常见问题（FAQ）

这是什么？为什么要做这个项目？

先认识两类模型

1. 单语言（纯文本）大模型

很多常见的大模型（例如某些版本的编程助手、办公助手）是单语言模型：它们只接受文字输入，也只输出文字。它们很擅长"读字"和"写字"，但天生"看不见"图片、视频，也读不懂 PDF 里的图表。

2. 多模态视觉模型

GLM-4.6V-Flash 是智谱开放平台提供的视觉识别模型。它专门负责"看"：能描述图片内容、识别图片中的文字（OCR）、看懂视频画面、解读 PDF/TXT 等文件，并把"看到的内容"转换成文字。

本项目解决什么问题？

如果你正在使用一个大模型，但它看不懂图片、视频、文件，通常有两个选择：

1. 换一个原生多模态的大模型（成本高、迁移麻烦）；
2. 给现有模型"外接"一个视觉模型——本项目做的就是这件事。

本项目相当于在纯文本大模型和视觉模型之间架了一座桥：大模型还是原来那个大模型，不需要重新训练，遇到图片/视频/文件时，通过 MCP 调起 GLM-4.6V-Flash 去"看"，再把文字结果拿回来，最终照样给你一个"看得懂图"的回答。

一句话总结：

主模型负责"思考"，视觉模型负责"看"，MCP 负责"牵线"，三者配合 = 多模态效果。

MCP 是什么？

MCP（Model Context Protocol，模型上下文协议）可以理解为"大模型的 USB 接口"。

• 以前：每个大模型想接入外部工具，都要为每个客户端单独开发对接代码；
• 现在：只要按 MCP 标准提供工具，任何支持 MCP 的客户端都能"即插即用"。

本项目就是一个标准的 MCP 服务器。它对外提供三个工具（analyze_image、analyze_video、analyze_file），客户端启动后会自动发现这些工具，并在需要时调用。

工作原理：它是怎么让大模型"看见"的？

以"问一张图片"为例，完整流程如下：

flowchart LR
    A["用户发来一张图片"] --> B["纯文本大模型（只会读字）"]
    B --> C["通过 MCP 调用 analyze_image"]
    C --> D["GLM-4.6V-Flash 视觉模型负责“看”"]
    D --> E["把“看到的内容”转成文字返回"]
    E --> F["大模型结合文字给出最终回答"]

简单来说：

1. 你向大模型提问，问题里带有图片/视频/文件；
2. 大模型发现自己"看不懂"媒体内容，就通过 MCP 把媒体交给 GLM-4.6V-Flash；
3. GLM-4.6V-Flash 完成视觉识别，把结果（一段文字描述）返回给大模型；
4. 大模型拿着这段文字，结合你的问题，给出最终回答。

对你来说，体验上就像大模型本身会看图一样——这就是"外接视觉模型实现多模态"的核心思路。

核心特性

• 免费模型：GLM-4.6V-Flash 是智谱开放平台的免费多模态模型（额度政策以智谱官方为准）；
• 不换模型、不用训练：原大模型保持不变，只是多了一个"外接眼睛"；
• 三种媒体：图片、视频、文件（PDF/TXT 等）都能理解；
• 支持本地文件：直接传本地文件路径，服务器会自动转成 Base64 data URI 上传；
• 深度思考可选：thinking 参数可开关模型的深度思考模式；
• 标准 MCP 协议：Codex、Cursor、Claude Desktop 等支持 MCP 的客户端都能接入；
• 轻量实现：用 httpx 直接调用 HTTP 接口，不依赖智谱 SDK。

底层 API 说明

本项目直接调用智谱开放平台的大模型接口，关键信息如下：

项目	值
接口地址	https://open.bigmodel.cn/api/paas/v4/chat/completions
模型 ID	glm-4.6v-flash
鉴权方式	请求头 Authorization: Bearer <ZHIPU_API_KEY>
请求库	httpx（直接 HTTP 调用，不依赖智谱 SDK）

支持的环境变量：

环境变量	作用	默认值
ZHIPU_API_KEY	智谱 API Key（必填，兼容 GLM_API_KEY）	无
GLM_API_BASE	覆盖接口地址	智谱官方地址
GLM_MODEL	覆盖模型 ID	glm-4.6v-flash
GLM_TIMEOUT	请求超时秒数	120
GLM_RETRY_DELAY	遇到 HTTP 429 限流时重试前的等待秒数	3
GLM_MAX_RETRIES	遇到 HTTP 429 限流时的最大重试次数	3

提供的 MCP 工具

MCP 工具	能做什么	常见用途
analyze_image	理解一张图片	OCR 识别、内容描述、表格解析、缺陷检测、把图转成提示词（Image2Prompt）等
analyze_video	理解一段视频（传视频 URL 或本地视频文件）	视频内容总结、关键画面描述、审核等
analyze_file	理解一个文件（PDF / TXT 等，传 URL 或本地文件）	文档解读、合同提取、报告总结等

所有工具都支持以下参数：

参数	说明	默认值
image / video / file	媒体地址，支持 http(s) URL、data URI 或本地文件路径	必填
prompt	你想让模型做什么/回答什么	不同工具各有默认提示词
thinking	是否开启深度思考模式（true/false）	false
temperature	采样温度（0~1），越低越保守，越高越有创造性	1.0
max_tokens	最大输出 token 数	4096

注意：一次请求只支持一种媒体（图片/视频/文件三选一），不支持同时传多种。

快速开始

1. 获取 API Key

到智谱开放平台申请：https://open.bigmodel.cn/usercenter/apikeys

申请后在控制台创建一个 Key，后面配置时要用。

2. 安装

方式一：从源码安装（GitHub 克隆）

需要 Python 3.10 或更高版本。

git clone https://github.com/<你的用户名>/glm-4.6v-flash-mcp.git
cd glm-4.6v-flash-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .   # 安装为 glm-mcp 命令

方式二：从 PyPI 安装（发布后，推荐）

pip install glm-4.6v-flash-mcp

3. 配置 API Key

把 .env.example 复制为 .env，然后填入你的 Key：

Copy-Item .env.example .env
# 然后用编辑器打开 .env，把 ZHIPU_API_KEY 改成你的真实 Key

也可以设置系统环境变量：

$env:ZHIPU_API_KEY = "你的Key"

注意事项：

• Key 只需写在项目目录的 .env 里，不需要写进 .mcp.json；
• 服务器启动时会固定读取自己项目目录下的 .env，无论从哪个目录启动；
• 也兼容 GLM_API_KEY 环境变量。

4. 验证安装

.\.venv\Scripts\python.exe scripts\smoke_test.py
.\.venv\Scripts\python.exe scripts\test_payload.py

两个脚本都运行成功，说明服务器和 API Key 都正常。

接入客户端

Codex / Cursor

先完成上面的安装，确保 glm-mcp 命令可用，然后：

项目级配置（把 .mcp.json 放到项目根目录）：

{
  "mcpServers": {
    "glm-4-6v-flash": {
      "command": "glm-mcp"
    }
  }
}

全局配置（编辑 ~/.codex/config.toml）：

[mcp_servers.glm-4-6v-flash]
command = "glm-mcp"

保存后重启 Codex / Cursor（或新开一个会话），MCP 服务器会自动启动，工具 analyze_image、analyze_video、analyze_file 就会出现。

Claude Desktop

把 claude_desktop_config.example.json 的内容合并到 Claude Desktop 的 claude_desktop_config.json（通常位于 %APPDATA%\Claude\）：

{
  "mcpServers": {
    "glm-4-6v-flash": {
      "command": "glm-mcp"
    }
  }
}

Key 通过环境变量 ZHIPU_API_KEY 设置，或放在启动目录的 .env 中。

其他支持 stdio 的 MCP 客户端

安装后直接启动：

glm-mcp

或使用 uvx（发布到 PyPI 后）：

uvx glm-4.6v-flash-mcp

在 Codex 桌面版中使用（资源方式）

当前 Codex 桌面版不会把外部 MCP 工具暴露为 mcp__* 函数，而是通过资源接口使用。本服务器额外提供了资源：

资源	说明
glm://help	使用说明与可直接使用的示例 URI
glm://analyze-image/{image}	图片分析（默认提示词），{image} 是 URL 编码的图片地址
glm://analyze-image/{image}/{prompt}	图片分析（自定义提示词）
glm://analyze/{payload}	图片/视频/文件通用分析，payload 是 base64url 编码的 JSON

在新会话里让 Codex 按以下步骤操作：

1. 调用 list_mcp_resources(server="glm-4-6v-flash") 查看资源；
2. 调用 read_mcp_resource(server="glm-4-6v-flash", uri="glm://help") 读取说明；
3. 按说明构造 glm://analyze/<payload>（或简版 glm://analyze-image/<URL编码的图片地址>），再调用 read_mcp_resource 读取分析结果。

手动调用示例

下面的 curl 请求等价于 analyze_image 工具内部的行为，方便你排查问题或直接测试 API：

curl -X POST https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $ZHIPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-4.6v-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "https://cdn.bigmodel.cn/static/logo/register.png"}},
        {"type": "text", "text": "这张图片讲了什么？"}
      ]
    }],
    "thinking": {"type": "disabled"}
  }'

请求结构说明：

• model：要使用的模型 ID；
• messages[0].content：一个数组，先放媒体块（image_url / video_url / file_url），再放文字提示词；
• thinking：{"type": "disabled"} 关闭深度思考，{"type": "enabled"} 开启。

注意事项

• 官方文档说明：一次请求内不支持同时理解文件、视频和图像，每个工具一次只传一种媒体。
• API Key 属于敏感信息，不要把 .env 提交到仓库（已加入 .gitignore）；.mcp.json 只包含启动命令，不含密钥，可以放心提交。
• 如需切换接口地址或模型 ID，可通过 GLM_API_BASE、GLM_MODEL 环境变量覆盖；请求超时可通过 GLM_TIMEOUT 调整。
• 遇到 HTTP 429 限流时会自动等待几秒后重试，可通过 GLM_RETRY_DELAY、GLM_MAX_RETRIES 调整。
• GLM-4.6V-Flash 为免费模型，但具体免费额度和使用政策以智谱开放平台官方说明为准。

常见问题（FAQ）

Q1：我的大模型本身好像也能看图，还需要这个项目吗？

如果你的模型本身就是原生多模态模型，就不需要。这个项目主要面向单语言（纯文本）大模型——它们只认文字，不认图片/视频/文件。通过本项目外接视觉模型，它们也能"看懂"媒体内容。

Q2：一次能同时传图片和视频吗？

不能。智谱官方文档要求一次请求只传一种媒体（图片、视频、文件三选一）。

Q3：怎么传本地文件？

直接把本地路径传给工具即可，例如 C:\photos\1.png。服务器会自动读取文件并转成 Base64 data URI 上传，你不需要手动转换。

Q4：API Key 应该写在哪里？

写在项目目录的 .env 里（复制 .env.example 修改即可），不需要写进 .mcp.json。也可以设置环境变量 ZHIPU_API_KEY（兼容 GLM_API_KEY）。

Q5：报错说没配置 API Key，怎么办？

检查是否已把 Key 填入 .env 并保存，或者是否设置了环境变量；确认 Key 没有前后空格，且格式形如 xxx.yyy。如果仍然不行，可以到智谱开放平台确认 Key 是否有效、账户是否有额度。

Q6：怎么改请求超时时间？

设置环境变量 GLM_TIMEOUT（单位秒），默认 120 秒。处理较大视频或文件时可以适当调大。

Q7：遇到 HTTP 429（访问量过大）怎么办？

服务器已内置自动重试：收到 429 时会等待 GLM_RETRY_DELAY（默认 3 秒）后重试，最多重试 GLM_MAX_RETRIES（默认 3）次。若仍失败，说明当前确实限流，请稍后再试，或调大重试等待时间。