glm4v-mcp

将智谱 GLM-4V 视觉模型封装为 MCP 服务器，通过 analyze_image 工具分析图片（支持本地图片路径或 Data URL）。

• 已发布到 npm：glm4v-mcp
• 使用 Model Context Protocol 标准协议，可接入任何支持 MCP 的客户端

功能特性

• 🖼️ 图片分析：analyze_image 工具，支持本地图片路径与 Data URL
• 🧠 GLM-4V 视觉模型：默认 glm-4v-flash（免费），可通过环境变量切换
• 🔌 双传输模式：stdio（进程直接拉起，推荐）与 http（Streamable HTTP，支持远程部署）
• 🌐 远程访问：HTTP 模式部署到服务器后，可被局域网/公网的 MCP 客户端连接

环境要求

• Node.js ≥ 20
• 智谱 API Key（开放平台申请），模型默认 glm-4v-flash

配置 API Key

三种方式任选其一（优先级：请求头 > 环境变量 > .env）：

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

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

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

环境变量一览

变量	默认值	说明
ZHIPU_API_KEY	—	必填（服务端配置时），智谱 API Key
MCP_PORT	30002	服务监听端口
GLM_MODEL	glm-4v-flash	智谱模型名，可换 glm-4v-plus 等

部署方式

方式一：npx 直接运行（最快）

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

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

MCP_TRANSPORT=stdio 环境变量等效于 --stdio 参数。

方式二：源码运行

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

方式三：Docker 部署

本地构建运行：

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

方式四：远程服务器部署（公网访问）

适用于把服务部署到云服务器，供局域网或公网设备上的 MCP 客户端连接。

# 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"}}}'

建议用进程管理器保持服务常驻

# 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

使用 MCP（客户端连接）

Claude Code（stdio 模式，推荐）

无需手动启动服务，Claude Code 会自动拉起进程。

方式一：项目级 .mcp.json 配置（推荐：key 随配置走，不依赖启动目录的 .env）

在项目根目录创建 .mcp.json：

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

env 块中的变量以环境变量形式传给进程，优先级高于 .env 文件（dotenv 不覆盖已存在的环境变量）。.mcp.json 含 API Key，建议加入 .gitignore，避免 key 提交到仓库。

方式二：命令行注册

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

# 查看连接状态
claude mcp list

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

Claude Code（http 模式，本机）

先启动服务，再注册：

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

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

Claude Code（http 模式，远程服务器）

服务部署在服务器（如 http://192.168.1.100:30002/mcp）时，本地无需启动服务：

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

其他 MCP 客户端（Claude Desktop / Cursor 等）

stdio 方式（Claude Desktop 的 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 方式（Claude Desktop / Cursor 等支持 HTTP 的客户端）：

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

远程服务器则把 url 换成服务器地址。

通过请求头传入 API Key（可选）

服务端未配置 ZHIPU_API_KEY 时，可在客户端配置中通过 headers 传入（服务端会优先使用请求头中的 key）：

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

命令行方式（Claude Code）：

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

注：ZHIPU_API_KEY 为 HTTP 请求头名，Node 服务端以小写 zhipu_api_key 读取，客户端原样发送即可。

工具：analyze_image

参数	类型	必填	说明
image	string	是	本地图片路径，或 data:image/...;base64,.... 形式的 Data URL
question	string	否	对图片的提问，默认「请描述这张图片」

支持的本地图片格式：png / jpg / jpeg / webp / gif。

常见问题

1. 连接不上 / 报错 ECONNREFUSED 服务没启动或端口不对。确认先运行 npx glm4v-mcp（或 Docker 容器），且 MCP_PORT 与注册的 URL 端口一致。

2. 调用报 401 ZHIPU_API_KEY 缺失或无效。检查服务启动时是否加载了 .env（服务需在含 .env 的目录启动），或直接在环境变量中设置。

3. 服务必须保持运行 HTTP 传输模式下客户端通过端口实时连接，服务进程停止后工具立即不可用。生产环境请用 pm2 / systemd / Docker 保持常驻。

4. stdio 模式 key 加载不到 stdio 模式的进程由客户端拉起（如 npx），.env 需位于客户端启动目录。最稳妥的做法：在客户端配置（.mcp.json / claude_desktop_config.json）的 env 块中直接写 ZHIPU_API_KEY（见上方示例），key 随配置走，与启动目录无关。

5. 远程访问提示超时 确认云服务器安全组/防火墙放行了对应端口，且客户端能 ping 通服务器。

License

MIT