[English](README_EN.md) | **简体中文**

---

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

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

## 目录

- [这是什么？为什么要做这个项目？](#这是什么为什么要做这个项目)
- [MCP 是什么？](#mcp-是什么)
- [工作原理：它是怎么让大模型"看见"的？](#工作原理它是怎么让大模型看见的)
- [核心特性](#核心特性)
- [底层 API 说明](#底层-api-说明)
- [提供的 MCP 工具](#提供的-mcp-工具)
- [快速开始](#快速开始)
- [接入客户端](#接入客户端)
- [在 Codex 桌面版中使用（资源方式）](#在-codex-桌面版中使用资源方式)
- [手动调用示例](#手动调用示例)
- [注意事项](#注意事项)
- [常见问题（FAQ）](#常见问题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`），客户端启动后会自动发现这些工具，并在需要时调用。

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

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

```mermaid
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 或更高版本。

```powershell
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 安装（发布后，推荐）**

```powershell
pip install glm-4.6v-flash-mcp
```

### 3. 配置 API Key

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

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

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

```powershell
$env:ZHIPU_API_KEY = "你的Key"
```

注意事项：

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

### 4. 验证安装

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

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

## 接入客户端

### Codex / Cursor

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

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

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

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

```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\`）：

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

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

### 其他支持 stdio 的 MCP 客户端

安装后直接启动：

```powershell
glm-mcp
```

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

```powershell
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：

```bash
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）次。若仍失败，说明当前确实限流，请稍后再试，或调大重试等待时间。