glm-vision-mcp

<div align="right">

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>

<p align="center"> <a href="#quick-start"><img src="https://img.shields.io/badge/Quick_Start-4CAF50?style=for-the-badge" alt="Quick Start" /></a> <a href="#license"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License" /></a> </p>

<p align="center"> <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript" /> <img src="https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white" alt="Node.js" /> <img src="https://img.shields.io/badge/MCP-black?style=flat&logo=i18next&logoColor=white" alt="MCP" /> <img src="https://img.shields.io/badge/Zod-3E67B1?style=flat&logo=zod&logoColor=white" alt="Zod" /> </p>

<p align="center"> <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Claude_Code-D97757?style=flat&logo=claude&logoColor=white" alt="Claude Code" /></a> <a href="https://opencode.ai"><img src="https://img.shields.io/badge/OpenCode-000000?style=flat&logo=openai&logoColor=white" alt="OpenCode" /></a> <a href="https://github.com/features/copilot"><img src="https://img.shields.io/badge/GitHub_Copilot-000000?style=flat&logo=github&logoColor=white" alt="GitHub Copilot" /></a> </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)

Contributing

Fork → branch → commit → open a pull request. Run npm test before pushing.

License

No LICENSE file detected. The package.json declares MIT. Add a LICENSE file to clarify terms before publishing.