MCP 服务器

glm-vision-mcp

A drop-in MCP vision server for Zhipu GLM Coding Plan, offering 8 vision tools powered by glm-5v-turbo with smart retry and caching.

README

English · 中文

</div>

<h1 align="center">glm-vision-mcp</h1>

<p align="center"> <strong>A drop-in MCP vision server for Zhipu GLM Coding Plan — same tools, more advanced vision model.</strong> <br /> <em>glm-5v-turbo · 8 Vision Tools · Dual Platform · Smart Retry · Local Cache</em> </p>

Features

Feature	Description
8 tools, same names	Identical tool names and parameter schemas as `@z_ai/mcp-server` — no prompt changes needed
Next-gen model by default	Uses glm-5v-turbo — improved accuracy and reasoning over the official glm-4.6v
Smart retry	429 / 5xx / network errors retried with exponential backoff; 4xx fails immediately — saves quota
Local result cache	LRU memory cache + optional disk persistence; same image + prompt skips the API call
`.env` support	`dotenv` loads your key from `.env` — no need to pass it through environment variables in development
Extended formats	Images: jpg, png, webp, gif, bmp, tiff. Video: mp4, mov, m4v, avi, mkv, webm, flv

Quick Start

# 1. Copy and edit .env
cp .env.example .env
# Set Z_AI_API_KEY=your_coding_plan_key

# 2. Add to your MCP client
claude mcp add glm-vision-mcp \
  --env Z_AI_API_KEY=YOUR_KEY \
  -- npx -y glm-vision-mcp

Usage

The server exposes 8 vision tools through stdio. Your MCP client handles tool discovery and invocation automatically.

Claude Code

claude mcp add glm-vision-mcp \
  --env Z_AI_API_KEY=YOUR_KEY \
  -- npx -y glm-vision-mcp

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "glm-vision-mcp": {
      "type": "local",
      "command": ["npx", "-y", "glm-vision-mcp"],
      "environment": { "Z_AI_API_KEY": "YOUR_KEY", "Z_AI_MODE": "ZHIPU" }
    }
  }
}

Cline / Roo Code

{
  "mcpServers": {
    "glm-vision-mcp": {
      "command": "npx",
      "args": ["-y", "glm-vision-mcp"],
      "env": { "Z_AI_API_KEY": "YOUR_KEY", "Z_AI_MODE": "ZHIPU" }
    }
  }
}

Architecture

flowchart LR
    Client["MCP Client\n(Claude Code / OpenCode / Cline)"]
    Server["glm-vision-mcp\n(stdio transport)"]
    Cache["Result Cache\n(LRU + disk)"]
    Vision["VisionService\n(unified handler)"]
    Chat["ChatService\n(retry + backoff)"]
    API["GLM Vision API\n(ZHIPU / ZAI)"]

    Client --> Server
    Server --> Cache
    Cache -->|"miss"| Vision
    Cache -->|"hit"| Server
    Vision --> Chat
    Chat --> API
    API --> Vision

Configuration

Variable	Default	Description
`Z_AI_API_KEY`	Required	Zhipu Coding Plan API key
`ZAI_MCP_API_KEY`	—	Fallback alias (auto-mapped)
`Z_AI_MODE`	`ZHIPU`	Platform: `ZHIPU` (China) or `ZAI` (International)
`Z_AI_VISION_MODEL`	`glm-5v-turbo`	Vision model ID
`Z_AI_VISION_MODEL_TEMPERATURE`	`0.8`	Sampling temperature
`Z_AI_VISION_MODEL_TOP_P`	`0.6`	Nucleus sampling
`Z_AI_VISION_MODEL_MAX_TOKENS`	`32768`	Max output tokens
`Z_AI_TIMEOUT`	`300000`	Request timeout (ms)
`Z_AI_RETRY_COUNT`	`2`	Max retries (retryable errors only)
`GLM_VISION_CACHE`	`true`	Enable result caching
`GLM_VISION_CACHE_TTL`	`604800`	Cache TTL in seconds (7 days)
`GLM_VISION_CACHE_MAX`	`100`	Max LRU cache entries
`GLM_IMAGE_MAX_SIZE_MB`	`5`	Max image file size
`GLM_VIDEO_MAX_SIZE_MB`	`8`	Max video file size

Directory Structure

src/
├── core/              # Environment, chat, vision, file, cache services
│   ├── environment.ts   # Dotenv + dual-platform + key fallback
│   ├── chat-service.ts  # GLM API calls with smart retry
│   ├── vision-service.ts  # Unified analysis orchestration
│   ├── file-service.ts  # Validation, base64 encoding, fingerprinting
│   └── cache.ts         # LRU + disk cache
├── tools/
│   ├── definitions.ts   # 8-tool data-driven definitions
│   └── registry.ts      # Tool registration on MCP server
├── prompts/             # 8 specialized system prompts
├── types/               # Error type hierarchy
└── utils/               # Logger, sanitization, validation
tests/
scripts/
  └── smoke.ts           # End-to-end verification with real key

Tech Stack

Layer	Technology
Runtime	Node.js ≥ 18
Language	TypeScript 5
Protocol	`@modelcontextprotocol/sdk`
Validation	Zod
Config	dotenv
Build	TypeScript compiler (`tsc`)
Dev	tsx (hot-reload), vitest (64 tests)