GLM Vision MCP Server

English | 简体中文

基于智谱AI GLM-4V多模态大模型的Model Context Protocol (MCP) 服务器实现，为Claude等AI助手提供专业的视觉分析能力。

快速开始

# 安装
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 安装（推荐）

最简单的安装方式，无需克隆仓库：

# 通过 PyPI 安装
pip install glm-vision-mcp

配置 Claude Desktop:

编辑配置文件:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加配置:

{
  "mcpServers": {
    "glm-vision": {
      "command": "uvx",
      "args": [
        "glm-vision-mcp"
      ],
      "env": {
        "GLM_API_KEY": "your_api_key_here"
      }
    }
  }
}

配置 Claude Code:

# 命令行配置
claude mcp add glm-vision --env GLM_API_KEY=your_api_key -- uvx glm-vision-mcp

或编辑 .claude.json:

{
  "mcpServers": {
    "glm-vision": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "glm-vision-mcp"
      ],
      "env": {
        "GLM_API_KEY": "your_api_key_here"
      }
    }
  }
}

方法2: 从源码安装

如需自定义或开发，可以从源码安装：

1. 克隆仓库

git clone https://github.com/kie0519/glm_vision_mcp.git
cd glm_vision_mcp

2. 安装依赖

pip install -e .
# 或
pip install fastmcp httpx

3. 配置 Claude Desktop

{
  "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

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客户端后,执行测试:

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,可根据需要调整:

# 文件大小限制
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. 实现工具函数和注册函数:

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 进行调试:

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开放平台
• Model Context Protocol
• FastMCP框架
• Claude Desktop