glm-vision-mcp

自建的 MCP（Model Context Protocol）服务器，底层调用智谱免费视觉模型 GLM-4.6V-Flash（glm-4.6v-flash，OpenAI 兼容接口）。任何支持 MCP 的客户端（Codex、Claude Desktop 等）都可以直接调用图片/视频/文件理解能力。

⚠️ 隐私与安全：调用本服务器时，图片、视频、PDF/Word 等文件的完整内容会发送到智谱云端处理。请勿上传身份证、银行卡、合同、内部办公文件等涉密资料；普通截图、公开文档可正常使用。API Key 只放在本地 .env（已被 .gitignore 排除），切勿提交到仓库。

详细安装、配置、注册与使用示例见 USAGE.md。

功能

工具	用途
analyze_image	单张或多张图片理解：OCR、复杂表格解析、内容理解、缺陷检测、Image2Prompt 等
analyze_video	视频内容理解、关键帧描述、时间线生成
analyze_file	PDF / TXT / Word 等文档问答、对比、关键信息抽取
check_config	检查 API Key、模型、接口地址是否就绪

支持本地文件路径（自动转成 data URI）、http(s) URL、data URI；支持思考模式开关（enabled / disabled / auto）。

调用前会自动做本地校验：文件大小（图片 20 MB / 视频 500 MB / 文件 50 MB）、图片分辨率（上限 5000 万像素）、加密 PDF、视频时长（30 分钟，需本机有 ffprobe）。超限会在上传前直接给出中文提示，不浪费请求。

快速开始

1. 到 智谱开放平台 注册并创建 API Key（GLM-4.6V-Flash 免费）。

2. 复制 .env.example 为 .env，填入你的 Key：

   ZHIPU_API_KEY=你的_API_KEY
   

3. 安装依赖并启动：

   python -m venv .venv
   .venv\Scripts\python.exe -m pip install -r requirements.txt
   .venv\Scripts\python.exe server.py
   

   也可以直接双击 run.bat（自动建虚拟环境、装依赖、启动）。

4. 自检（不需要 Key）：

   .venv\Scripts\python.exe tests\smoke_test.py
   

   正常会输出可用工具列表。

注册到 MCP 客户端

核心就是让客户端用以下命令拉起本服务器：

command: <项目绝对路径>\.venv\Scripts\python.exe
args:    ["<项目绝对路径>\\server.py"]

Codex CLI（~/.codex/config.toml）

[mcp_servers.glm-vision]
command = "C:\\path\\to\\glm-vision-mcp\\.venv\\Scripts\\python.exe"
args = ["C:\\path\\to\\glm-vision-mcp\\server.py"]
cwd = "C:\\path\\to\\glm-vision-mcp"

Codex 桌面版

在「设置 → MCP 服务器」中新增一条，command 填 .venv\Scripts\python.exe 的绝对路径，args 填 server.py 的绝对路径。

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "glm-vision": {
      "command": "C:\\path\\to\\glm-vision-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\glm-vision-mcp\\server.py"]
    }
  }
}

API Key 放在项目 .env 里即可，客户端进程会自动读取，不需要写进客户端配置。

可选配置

通过环境变量或 .env 覆盖：

GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
GLM_MODEL=glm-4.6v-flash

常用问题

• API Key 无效或已过期（401/403）：检查 ZHIPU_API_KEY 配置，去智谱平台重新生成。
• 余额或免费额度不足（402）：到智谱开放平台查看账户额度。
• 限流/访问量过大（429/1305）：免费模型高峰期常见，服务器会自动重试，仍失败请稍后再试。
• 内容过大（413）：本地前置校验已拦截大部分超限文件；仍出现请进一步压缩。
• 服务端故障（5xx）：智谱服务暂时不可用，稍后重试。
• “未配置 API Key”：.env 没创建，或变量名不是 ZHIPU_API_KEY。
• 不支持同时输入：GLM-4.6V-Flash 不允许图片、视频、文件混用，一次调用只传一种类型。
• 启动后无输出：stdio 模式下服务器静默等待客户端连接，属正常现象。

测试

rem 单元测试（请求构造、图片编码、响应解析，mock 方式，不需要 Key）
.venv\Scripts\python.exe -m unittest discover -s tests -v

rem MCP 握手测试（启动 stdio 服务器并列出工具，不需要 Key）
.venv\Scripts\python.exe tests\smoke_test.py

rem 真实调用测试（需要 .env 里有 Key，会自动重试限流）
.venv\Scripts\python.exe tests\live_test.py <你的图片路径>