glm-vision-mcp 1.0.1
基于智谱AI GLM-4V多模态大模型的MCP服务器，提供专业的视觉分析能力
License: MIT
Requires Python: >=3.8
Keywords: mcp, glm, vision, multimodal, zhipuai, ai, computer-vision

# GLM Vision MCP Server

[![PyPI version](https://badge.fury.io/py/glm-vision-mcp.svg)](https://badge.fury.io/py/glm-vision-mcp)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[English](./README_EN.md) | 简体中文

基于智谱AI GLM-4V多模态大模型的Model Context Protocol (MCP) 服务器实现，为Claude等AI助手提供专业的视觉分析能力。

## 快速开始

```bash
# 安装
pip install glm-vision-mcp

# 配置 Claude Code
claude mcp add glm-vision --env GLM_API_KEY=your_api_key -- uvx glm-vision-mcp

# 或通过 uvx 直接使用
uvx glm-vision-mcp
```

**PyPI包地址**: https://pypi.org/project/glm-vision-mcp/

## 项目简介

GLM Vision MCP Server 是一个标准的 MCP 协议服务器，通过集成智谱AI的GLM-4V多模态大模型，为开发者提供8个专业的视觉分析工具。本项目采用stdio传输模式，支持图像和视频的多模态分析，可无缝集成到Claude Desktop、Claude Code等支持MCP协议的客户端中。

## 技术规格

### MCP配置

- **协议版本**: MCP 1.0
- **传输模式**: stdio (标准输入输出通信)
- **服务器类型**: FastMCP

### 模型配置

| 参数 | 值 | 说明 |
|------|------|------|
| 模型 | glm-4.5v | 智谱AI多模态视觉模型 |
| API端点 | https://open.bigmodel.cn/api/paas/v4/chat/completions | 智谱AI API地址 |
| Temperature | 0.8 | 控制输出随机性 |
| Top P | 0.6 | 核采样参数 |
| Max Tokens | 16384 | 最大输出token数 |
| 超时时间 | 120秒 | API请求超时限制 |

### 文件支持规格

| 类型 | 支持格式 | 最大文件大小 | 编码方式 |
|------|---------|-------------|---------|
| 图片 | PNG, JPG, JPEG | 5MB | Base64 Data URI |
| 视频 | MP4, MOV, M4V | 8MB | Base64 Data URI |

## 系统要求

- Python 3.8 或更高版本
- 智谱AI API Key
- 支持的操作系统: Windows, macOS, Linux

## 安装部署

### 方法1: 使用 uvx 安装（推荐）

最简单的安装方式，无需克隆仓库：

```bash
# 通过 PyPI 安装
pip install glm-vision-mcp
```

**配置 Claude Desktop:**

编辑配置文件:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

添加配置:

```json
{
  "mcpServers": {
    "glm-vision": {
      "command": "uvx",
      "args": [
        "glm-vision-mcp"
      ],
      "env": {
        "GLM_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**配置 Claude Code:**

```bash
# 命令行配置
claude mcp add glm-vision --env GLM_API_KEY=your_api_key -- uvx glm-vision-mcp
```

或编辑 `.claude.json`:

```json
{
  "mcpServers": {
    "glm-vision": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "glm-vision-mcp"
      ],
      "env": {
        "GLM_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### 方法2: 从源码安装

如需自定义或开发，可以从源码安装：

**1. 克隆仓库**

```bash
git clone https://github.com/kie0519/glm_vision_mcp.git
cd glm_vision_mcp
```

**2. 安装依赖**

```bash
pip install -e .
# 或
pip install fastmcp httpx
```

**3. 配置 Claude Desktop**

```json
{
  "mcpServers": {
    "glm-vision": {
      "command": "python",
      "args": [
        "D:/path/to/glm_vision_mcp/server.py"
      ],
      "env": {
        "GLM_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**4. 配置 Claude Code**

```bash
claude mcp add glm-vision --env GLM_API_KEY=your_api_key -- python D:/path/to/glm_vision_mcp/server.py
```

### 获取 API Key

访问智谱AI开放平台获取 API Key: https://open.bigmodel.cn/

### 5. 验证安装

重启MCP客户端后,执行测试:

```bash
python server.py
```

如无报错则安装成功。

## 工具清单

### 1. ui_to_artifact

**功能描述**: 将UI截图转换为代码/提示词/设计规范/描述

**适用场景**:
- 从UI设计生成前端代码
- 创建AI提示词以重建UI
- 提取设计规范文档
- 生成UI自然语言描述

**输入参数**:
- `image_source` (string): UI截图路径
- `output_type` (string): 输出类型,可选值: 'code'/'prompt'/'spec'/'description'
- `prompt` (string): 详细需求描述

**输出内容**:

根据 `output_type` 返回不同格式:
- `code`: 完整可运行代码 + 结构说明 + 样式说明
- `prompt`: AI生成提示词 + 结构分解 + 使用说明
- `spec`: 设计系统规范文档
- `description`: 自然语言UI描述

### 2. extract_text_from_screenshot

**功能描述**: 从截图中提取和识别文本内容

**适用场景**:
- 提取IDE/编辑器中的代码
- 复制终端/控制台输出
- 获取文档或文章文本
- 提取配置文件、日志或API响应

**输入参数**:
- `image_source` (string): 包含文本的截图路径
- `prompt` (string): 提取要求描述

**输出内容**:
- 提取的完整文本(保留格式)
- 内容类型识别
- 编程语言/格式检测
- OCR修正说明
- 质量注释

### 3. diagnose_error_screenshot

**功能描述**: 诊断和分析截图中的错误消息和异常

**适用场景**:
- 错误消息或异常截图
- 堆栈跟踪或错误日志
- 编译或构建失败
- 运行时错误或崩溃

**输入参数**:
- `image_source` (string): 错误截图路径
- `prompt` (string): 错误上下文和帮助需求

**输出内容**:
- 错误摘要(类型/位置/严重性)
- 根因分析
- 逐步修复方案 + 代码片段
- 预防策略和最佳实践
- 附加注意事项

### 4. understand_technical_diagram

**功能描述**: 分析和解释技术图表、架构设计

**适用场景**:
- 系统架构图
- 流程图
- UML图(类图/序列图/活动图等)
- 数据库ER图
- 网络拓扑图

**输入参数**:
- `image_source` (string): 技术图表路径
- `prompt` (string): 分析需求描述

**输出内容**:
- 图表概览(类型/目的/标准)
- 组件清单及职责
- 关系和数据流分析
- 架构模式评估
- 文本表示(Mermaid/PlantUML)

### 5. analyze_data_visualization

**功能描述**: 分析数据可视化、图表、仪表板

**适用场景**:
- 各类图表(折线/柱状/饼图/散点图等)
- 仪表板或监控面板
- 统计可视化
- 性能指标显示

**输入参数**:
- `image_source` (string): 数据可视化截图路径
- `prompt` (string): 分析需求描述

**输出内容**:
- 可视化摘要(类型/指标/时间段)
- 关键指标数值
- 趋势和模式分析
- 异常和洞察
- 可执行建议

### 6. ui_diff_check

**功能描述**: 对比两个UI截图的差异

**适用场景**:
- 对比设计稿vs实现UI
- 视觉回归测试
- 检查版本间UI一致性
- 识别布局问题或视觉bug
- 验证UI实现准确性

**输入参数**:
- `expected_image_source` (string): 预期UI截图路径
- `actual_image_source` (string): 实际UI截图路径
- `prompt` (string): 对比需求描述

**输出内容**:
- 整体评估(相似度/主要差异)
- 详细差异(按严重程度分级)
- 布局/内容/样式问题清单
- 推荐修复方案(含CSS代码)
- 测试注释

### 7. analyze_image

**功能描述**: 通用图像分析

**适用场景**: 作为后备工具,当其他专用工具都不适用时使用,提供灵活的图像分析能力

**输入参数**:
- `image_source` (string): 任意图像路径
- `prompt` (string): 详细分析需求描述

**输出内容**:
- 针对用户请求的主要响应
- 详细观察结果
- 上下文和分析
- 附加注释

### 8. analyze_video

**功能描述**: 通用视频分析

**适用场景**: 分析视频内容,理解视频场景,回答视频相关问题

**输入参数**:
- `video_source` (string): 视频文件路径
- `prompt` (string): 视频分析需求描述

**输出内容**:
- 视频内容摘要
- 场景和动作分析
- 关键帧描述
- 针对性回答

## 配置参数

配置文件位于 `config.py`,可根据需要调整:

```python
# 文件大小限制
MAX_IMAGE_SIZE = 5 * 1024 * 1024  # 5MB
MAX_VIDEO_SIZE = 8 * 1024 * 1024  # 8MB

# 支持的文件格式
SUPPORTED_IMAGE_FORMATS = {'.png', '.jpg', '.jpeg'}
SUPPORTED_VIDEO_FORMATS = {'.mp4', '.mov', '.m4v'}

# GLM API配置
GLM_API_URL = "https://open.bigmodel.cn/api/paas/v4/chat/completions"
MODEL_NAME = "glm-4.5v"

# 模型参数
TEMPERATURE = 0.8  # 控制随机性(0.0-1.0)
TOP_P = 0.6        # 核采样参数(0.0-1.0)
MAX_TOKENS = 16384 # 最大响应长度

# 服务器元数据
SERVER_NAME = "GLM Vision Scene Server"
SERVER_VERSION = "1.0.0"
```

## 故障排除

### 环境变量未设置

**错误**: `RuntimeError: GLM_API_KEY environment variable is not set`

**解决方案**:
1. 确认已正确设置 `GLM_API_KEY` 环境变量
2. 检查MCP客户端配置文件中的 `env` 配置
3. 重启MCP客户端使配置生效

### 文件格式不支持

**错误**: `ValueError: Unsupported image/video format`

**解决方案**:
1. 确认文件格式在支持列表中
2. 检查文件扩展名是否正确
3. 必要时转换文件格式

### 文件大小超限

**错误**: `ValueError: File size exceeds limit`

**解决方案**:
1. 压缩图片/视频文件
2. 在 `config.py` 中调整大小限制
3. 重启MCP服务器使配置生效

### API调用失败

**错误**: `RuntimeError: GLM API request failed`

**解决方案**:
1. 检查网络连接
2. 验证API Key是否有效
3. 确认智谱AI账户额度充足
4. 查看详细错误日志

### MCP服务器无法连接

**解决方案**:
1. 验证配置文件路径正确
2. 确认Python解释器路径正确
3. 检查MCP客户端日志
4. 尝试命令行直接运行 `python server.py` 测试

## 项目结构

```
glm_vision_mcp/
├── server.py                 # MCP服务器入口
├── config.py                 # 配置文件
├── api_client.py             # GLM API客户端
├── utils.py                  # 工具函数
├── __init__.py               # 包初始化
├── tools/                    # 工具模块
│   ├── __init__.py           # 工具注册
│   ├── ui_to_artifact.py     # UI转代码工具
│   ├── text_extraction.py    # 文本提取工具
│   ├── error_diagnosis.py    # 错误诊断工具
│   ├── diagram_analysis.py   # 图表分析工具
│   ├── data_viz.py           # 数据可视化工具
│   ├── ui_diff.py            # UI对比工具
│   ├── video_analysis.py     # 视频分析工具
│   └── general_image.py      # 通用图像分析工具
├── prompts/                  # 系统提示词模板
│   ├── __init__.py           # 提示词模块初始化
│   ├── ui_to_artifact.py     # UI转代码提示词
│   ├── text_extraction.py    # 文本提取提示词
│   ├── error_diagnosis.py    # 错误诊断提示词
│   ├── diagram_analysis.py   # 图表分析提示词
│   ├── data_viz.py           # 数据可视化提示词
│   ├── ui_diff.py            # UI对比提示词
│   ├── video_analysis.py     # 视频分析提示词
│   └── general_image.py      # 通用图像分析提示词
└── data/                     # 示例数据
```

## 开发指南

### 添加新工具

1. 在 `tools/` 目录创建新的工具模块
2. 实现工具函数和注册函数:

```python
from fastmcp import FastMCP
from api_client import call_glm_api
from utils import file_to_data_uri, load_prompt_template

def register_new_tool(mcp: FastMCP):
    @mcp.tool()
    async def new_tool(image_source: str, prompt: str) -> str:
        """工具描述"""
        system_prompt = load_prompt_template("new_tool")
        data_uri = file_to_data_uri(image_source)

        result = await call_glm_api(
            system_prompt=system_prompt,
            user_prompt=prompt,
            media_data_uris=[data_uri]
        )

        return result
```

3. 在 `tools/__init__.py` 中注册新工具
4. 在 `prompts/` 目录创建对应提示词文件

### 调试工具

使用 MCP Inspector 进行调试:

```bash
npx @modelcontextprotocol/inspector python server.py
```

## 许可证

MIT License

## 作者信息

- 作者: kie
- 项目主页: https://github.com/kie0519/glm_vision_mcp
- 问题反馈: https://github.com/kie0519/glm_vision_mcp/issues

## 相关链接

- [智谱AI开放平台](https://open.bigmodel.cn/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP框架](https://github.com/jlowin/fastmcp)
- [Claude Desktop](https://claude.ai/download)