# GLM_vision

**Repository Path**: Westin_x/glm_vision

## Basic Information

- **Project Name**: GLM_vision
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-09
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GLM Vision MCP

一个通用的 Python MCP 服务，把图片、视频和视觉文档识别委托给智谱 `glm-4.6v-flash`。
适合 Codex、Claude Desktop、Cursor、Cherry Studio，以及任何支持 MCP `stdio` 或 Streamable HTTP 的客户端。

## 功能

- `analyze_image`：图片理解、OCR、截图/UI 分析、表格与图表识别。
- `analyze_video`：视频 URL 内容理解与时间线总结。
- `analyze_document`：PDF 或文本文件 URL 的视觉/结构化问答。
- `analyze_media`：无法预先判断媒体类型时自动推断。
- 支持 `stdio` 与 Streamable HTTP 两种传输。
- Base64 大小限制、本地目录白名单、HTTP Bearer 鉴权、Origin 检查和请求体限制。
- 自动加载项目目录的 `.env` 文件，无需手工导出环境变量。

模型限制与智谱官方文档一致：图片、视频和文件不能在同一次请求中混用。
图片支持 URL、Base64、Data URI 和受控本地路径；视频与文档使用 URL。

## 环境要求

- Python 3.11 或更高版本。
- Linux（Debian/Ubuntu）或 Windows 10/11。
- 一个智谱开放平台的 API Key（`ZAI_API_KEY`）。

## 快速开始

### Linux / macOS

```bash
bash scripts/bootstrap.sh
```

### Windows PowerShell

```powershell
.\scripts\bootstrap.ps1
```

`bootstrap` 会自动完成：

1. 检测 Python 3.11+ 环境。
2. 在项目目录创建 `.venv` 虚拟环境并安装 `glm-vision-mcp`。
3. 生成 `.env`（自动创建随机 `GLM_VISION_MCP_AUTH_TOKEN`；保留已有值）。
4. 启动服务：Linux 安装为 systemd 服务，Windows 后台运行。
5. 打印 Codex / Claude Desktop / Cursor / Cherry Studio 的 MCP 配置。

常用参数：

```bash
# 只安装不启动
bash scripts/bootstrap.sh --no-start

# 自定义监听地址与端口
bash scripts/bootstrap.sh --host 0.0.0.0 --port 9000

# 同时安装 Codex Skill 并输出配置
bash scripts/bootstrap.sh --install-skill --print-config
```

首次运行时 `.env` 中 `ZAI_API_KEY` 为空，工具调用会返回配置错误；填入智谱 API Key 后重启服务即可：

```bash
vim .env
bash scripts/run.sh --transport streamable-http --host 127.0.0.1 --port 8000
```

## 配置

复制 `.env.example` 为 `.env` 后按需修改：

```dotenv
# 智谱开放平台 API Key（必填）
ZAI_API_KEY=YOUR_ZAI_API_KEY

# 模型名称
GLM_VISION_MODEL=glm-4.6v-flash

# HTTP 访问令牌；监听非回环地址时必填
GLM_VISION_MCP_AUTH_TOKEN=CHANGE_ME_TO_A_RANDOM_SECRET

# 默认仅本机访问
GLM_VISION_HTTP_HOST=127.0.0.1
GLM_VISION_HTTP_PORT=8000
```

生成随机令牌：

```bash
openssl rand -hex 32
```

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `ZAI_API_KEY` | 无 | 调用工具时必须提供 |
| `GLM_VISION_MODEL` | `glm-4.6v-flash` | 模型名称 |
| `GLM_VISION_API_BASE_URL` | `https://open.bigmodel.cn/api/paas/v4` | API 根地址 |
| `GLM_VISION_TIMEOUT_SECONDS` | `60` | 请求超时 |
| `GLM_VISION_MAX_MEDIA_BYTES` | `20971520` | Base64/本地图片最大字节数 |
| `GLM_VISION_MAX_URL_LENGTH` | `4096` | 媒体 URL 最大长度 |
| `GLM_VISION_MAX_QUESTION_CHARS` | `20000` | 提问最大字符数 |
| `GLM_VISION_ALLOW_HTTP_URLS` | `false` | 是否允许明文 HTTP 媒体 URL |
| `GLM_VISION_ALLOW_LOCAL_FILES` | `false` | 是否允许 stdio 读取本地图片 |
| `GLM_VISION_LOCAL_ROOTS` | 空 | 本地文件白名单目录 |
| `GLM_VISION_MAX_HTTP_BODY_BYTES` | `29360128` | 请求体最大字节数 |
| `GLM_VISION_HTTP_HOST` | `127.0.0.1` | HTTP 监听地址 |
| `GLM_VISION_HTTP_PORT` | `8000` | HTTP 监听端口 |
| `GLM_VISION_MCP_AUTH_TOKEN` | 空 | HTTP Bearer 令牌 |
| `GLM_VISION_ALLOWED_ORIGINS` | 空 | 允许的浏览器 Origin |

## 运行方式

### 本机 stdio（推荐单机客户端）

```bash
.venv/bin/glm-vision-mcp --transport stdio
```

Windows：

```powershell
.\.venv\Scripts\glm-vision-mcp.exe --transport stdio
```

允许读取本地图片时还需配置：

```dotenv
GLM_VISION_ALLOW_LOCAL_FILES=true
GLM_VISION_LOCAL_ROOTS=/home/user/Pictures:/home/user/Scans
```

路径列表使用当前操作系统的路径分隔符；Windows 为分号，Linux/macOS 为冒号。
HTTP 模式始终拒绝本地路径。

### Streamable HTTP（共享服务）

```bash
.venv/bin/glm-vision-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

访问地址为 `http://127.0.0.1:8000/mcp`。

监听非回环地址时必须设置访问令牌：

```bash
.venv/bin/glm-vision-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

客户端请求头：

```text
Authorization: Bearer <GLM_VISION_MCP_AUTH_TOKEN>
```

浏览器来源默认被拒绝。确需浏览器访问时，使用逗号分隔的完整 Origin：

```dotenv
GLM_VISION_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
```

## 客户端接入

### Codex

编辑 `~/.codex/config.toml`：

```toml
[mcp_servers.glm-vision]
enabled = true
type = "http"
url = "http://127.0.0.1:8000/mcp"
bearer_token_env_var = "GLM_VISION_MCP_TOKEN"
```

在 shell 环境或 `~/.codex/.env` 中设置：

```dotenv
GLM_VISION_MCP_TOKEN=<GLM_VISION_MCP_AUTH_TOKEN>
```

重启 Codex 后工具自动出现。

### Claude Desktop

编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "glm-vision": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer <GLM_VISION_MCP_AUTH_TOKEN>"
      }
    }
  }
}
```

### Cursor

编辑 `~/.cursor/mcp.json` 或项目 `.mcp.json`：

```json
{
  "mcpServers": {
    "glm-vision": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer <GLM_VISION_MCP_AUTH_TOKEN>"
      }
    }
  }
}
```

### Cherry Studio

设置 → MCP 服务器 → 添加：

- 类型：`Streamable HTTP`
- URL：`http://127.0.0.1:8000/mcp`
- 请求头：`Authorization: Bearer <GLM_VISION_MCP_AUTH_TOKEN>`

## 部署为 systemd 服务（Linux）

适合作为常驻后台服务运行。完整步骤见 `deploy/README.md`。

```bash
# 创建运行用户
sudo useradd --system --home-dir /nonexistent --shell /usr/sbin/nologin glmvision

# 安装服务单元
sudo install -m 644 deploy/glm-vision-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now glm-vision-mcp.service

# 查看状态与日志
systemctl status glm-vision-mcp.service
journalctl -u glm-vision-mcp.service -f
```

## 远程访问

- 若服务器与客户端在同一局域网，把 `GLM_VISION_HTTP_HOST` 设为 `0.0.0.0`，使用 `http://<服务器IP>:8000/mcp` 访问。
- 跨网络访问建议使用 Tailscale 或 WireGuard 等私有网络，不要直接暴露公网端口。
- 暴露公网必须由反向代理终止 TLS，并保持 Bearer 鉴权。

Tailscale 示例：

```bash
sudo tailscale up --hostname=glm-vision
# 远程访问地址：http://glm-vision.<你的tailnet域名>:8000/mcp
```

## 工具输入

URL 图片：

```json
{
  "source": {"type": "url", "url": "https://example.com/image.png"},
  "question": "提取图片中的全部文字，并保持阅读顺序。"
}
```

Base64 图片：

```json
{
  "source": {"type": "base64", "data": "<BASE64>", "mime_type": "image/png"},
  "question": "识别界面中的错误信息并给出排查建议。"
}
```

Data URI 图片：

```json
{
  "source": {"type": "data_uri", "data_uri": "data:image/png;base64,<BASE64>"},
  "question": "描述这张图片。"
}
```

视频：

```json
{
  "source": {"type": "url", "url": "https://example.com/video.mp4"},
  "question": "按时间顺序列出关键事件。"
}
```

## 开发

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m mypy src
```

默认测试不会消耗智谱额度。只有显式提供 `ZAI_API_KEY` 的手动联调才会调用真实模型。

## 项目结构

```text
src/glm_vision_mcp/   # 服务实现
scripts/bootstrap.*   # 一键安装/配置/启动入口
scripts/run.*         # 手动启动入口
scripts/install.*     # 仅安装依赖的轻量脚本
deploy/               # systemd 服务单元与部署文档
examples/             # 客户端配置样例
skill/                # Codex 配套 Skill
```

## 许可证

MIT License