glm4v-mcp

Wrap Zhipu GLM-4V vision model as an MCP server, analyze images via the analyze_image tool (supports local image paths or Data URL).

• Published on npm: glm4v-mcp

• Uses the Model Context Protocol standard protocol, compatible with any MCP-supporting client

Features

• 🖼️ Image analysis: analyze_image tool, supports local image paths and Data URL

• 🧠 GLM-4V vision model: defaults to glm-4v-flash (free), switchable via environment variable

• 🔌 Dual transport modes: stdio (direct process launch, recommended) and http (Streamable HTTP, supports remote deployment)

• 🌐 Remote access: After deploying in HTTP mode on a server, it can be connected by MCP clients on LAN/Internet

Related MCP server: Look At Pic MCP

Requirements

• Node.js ≥ 20

• Zhipu API Key (apply on open platform), model defaults to glm-4v-flash

Configure API Key

Choose one of three methods (priority: Request header > Environment variable > .env):

# 方式一：请求头（每次请求传入，支持不同客户端用不同 key）
# 在 MCP 客户端配置中加 headers（见下方「使用 MCP」章节）

# 方式二：环境变量
export ZHIPU_API_KEY=你的key

# 方式三：在启动目录创建 .env
ZHIPU_API_KEY=你的key

Environment Variables

Deployment Methods

Method 1: Run directly with npx (fastest)

# stdio 模式（推荐）：由 MCP 客户端直接拉起进程，无需手动启动
npx glm4v-mcp --stdio

# http 模式：手动启动，服务监听在 http://localhost:30002/mcp
npx glm4v-mcp

Environment variable MCP_TRANSPORT=stdio is equivalent to the --stdio flag.

Method 2: Run from source

git clone https://github.com/1340896123/glm4v-mcp.git
cd glm4v-mcp
npm install
npm start  # 或 node glm4v-mcp.mjs

Method 3: Docker deployment

Build and run locally:

docker build -t glm4v-mcp .
docker run -d -p 30002:30002 -e ZHIPU_API_KEY=你的key --name glm4v-mcp glm4v-mcp

Method 4: Remote server deployment (public access)

Suitable for deploying the service on a cloud server for MCP clients on LAN or internet devices to connect.

# 1. 服务器上安装 Node.js ≥ 20 或 Docker，然后任选方式一/二/三启动
# 2. 确保防火墙放行端口：
ufw allow 30002/tcp   # Ubuntu 防火墙示例

# 3. 验证本机可访问：
curl -X POST http://localhost:30002/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

It is recommended to use a process manager to keep the service alive

# pm2 方式
npm i -g pm2
pm2 start glm4v-mcp.mjs --name glm4v-mcp
pm2 save && pm2 startup

# 或 systemd（Linux）方式：/etc/systemd/system/glm4v-mcp.service
# [Service]
# ExecStart=/usr/bin/node /opt/glm4v-mcp/glm4v-mcp.mjs
# Restart=always
# Environment=ZHIPU_API_KEY=你的key
# [Install]
# WantedBy=multi-user.target

Using MCP (Client Connection)

Claude Code (stdio mode, recommended)

No need to manually start the service; Claude Code will automatically launch the process.

Method 1: Project-level .mcp.json configuration (recommended: key travels with config, independent of the .env in the startup directory)

Create .mcp.json in the project root:

{
  "mcpServers": {
    "glm4v": {
      "command": "npx",
      "args": ["-y", "glm4v-mcp", "--stdio"],
      "env": {
        "GLM_MODEL": "glm-4.6v-flash",
        "ZHIPU_API_KEY": "你的key"
      }
    }
  }
}

Variables in the env block are passed to the process as environment variables, with higher priority than the .env file (dotenv does not overwrite existing environment variables). .mcp.json contains the API Key; it is recommended to add it to .gitignore to avoid committing the key to the repository.

Method 2: Command-line registration

claude mcp add glm4v -- npx -y glm4v-mcp --stdio

# 查看连接状态
claude mcp list

# 重启会话后即可使用，或在会话中执行 /mcp 查看

Claude Code (http mode, local)

Start the service first, then register:

npx glm4v-mcp  # 启动服务（保持运行）

# 注册（一次即可，配置写入 ~/.claude.json）
claude mcp add --transport http glm4v http://localhost:30002/mcp

Claude Code (http mode, remote server)

When the service is deployed on a server (e.g., http://192.168.1.100:30002/mcp), no need to start the service locally:

claude mcp add --transport http glm4v http://192.168.1.100:30002/mcp

Other MCP Clients (Claude Desktop / Cursor, etc.)

stdio mode (Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "glm4v": {
      "command": "npx",
      "args": ["-y", "glm4v-mcp", "--stdio"],
      "env": {
        "GLM_MODEL": "glm-4.6v-flash",
        "ZHIPU_API_KEY": "你的key"
      }
    }
  }
}

http mode (Claude Desktop / Cursor and other HTTP-supporting clients):

{
  "mcpServers": {
    "glm4v": {
      "type": "http",
      "url": "http://localhost:30002/mcp"
    }
  }
}

For remote servers, replace url with the server address.

Passing API Key via Request Header (Optional)

When the server does not have ZHIPU_API_KEY configured, it can be passed via headers in the client configuration (the server will prioritize the key in the request header):

{
  "mcpServers": {
    "glm4v": {
      "type": "http",
      "url": "http://localhost:30002/mcp",
      "headers": {
        "ZHIPU_API_KEY": "你的key"
      }
    }
  }
}

Command-line method (Claude Code):

claude mcp add --transport http glm4v http://localhost:30002/mcp \
  --header "ZHIPU_API_KEY=你的key"

Note: ZHIPU_API_KEY is the HTTP header name. The Node server reads it as lowercase zhipu_api_key, so the client sends it as is.

Tool: analyze_image

Supported local image formats: png / jpg / jpeg / webp / gif.

FAQ

1. Cannot connect / Error ECONNREFUSED Service not started or wrong port. Make sure you have run npx glm4v-mcp (or Docker container) first, and that MCP_PORT matches the port in the registered URL.

2. Call returns 401 ZHIPU_API_KEY is missing or invalid. Check if the service loaded .env at startup (the service needs to be started in a directory containing .env), or set it directly in the environment variables.

3. Service must stay running In HTTP transport mode, the client connects via port in real time; if the service process stops, the tool becomes unavailable immediately. In production, use pm2 / systemd / Docker to keep it alive.

4. stdio mode key not loaded In stdio mode, the process is launched by the client (e.g., npx), and .env must be in the client's startup directory. The safest approach: write ZHIPU_API_KEY directly in the env block of the client configuration (.mcp.json / claude_desktop_config.json) as shown above; the key travels with the config, independent of the startup directory.

5. Remote access timeout Make sure the cloud server's security group/firewall allows the corresponding port, and the client can ping the server.

License

MIT