glm4v-mcp

Dieses Paket kapselt das GLM-4V-Visionmodell von Zhipu als MCP-Server und analysiert Bilder über das Tool analyze_image (unterstützt lokale Bildpfade oder Data-URLs).

• Veröffentlicht auf npm: glm4v-mcp

• Verwendet das Standardprotokoll Model Context Protocol und kann in jeden MCP-fähigen Client integriert werden.

Funktionen

• 🖼️ Bildanalyse: Das Tool analyze_image unterstützt lokale Bildpfade und Data-URLs

• 🧠 GLM-4V-Visionmodell: Standardmäßig glm-4v-flash (kostenlos), über Umgebungsvariable umschaltbar

• 🔌 Zwei Transportmodi: stdio (Prozess wird direkt gestartet, empfohlen) und http (Streamable HTTP, unterstützt Remote-Bereitstellung)

• 🌐 Remote-Zugriff: Nach der Bereitstellung im HTTP-Modus auf einem Server kann der Dienst von MCP-Clients im LAN oder öffentlichen Netz verbunden werden.

Related MCP server: Look At Pic MCP

Systemanforderungen

• Node.js ≥ 20

• Zhipu-API-Key (auf der offenen Plattform beantragen); Standardmodell: glm-4v-flash

API-Key konfigurieren

Eine der drei folgenden Methoden wählen (Priorität: Request-Header > Umgebungsvariable > .env):

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

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

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

Übersicht der Umgebungsvariablen

Bereitstellungsmethoden

Methode 1: Direkt mit npx ausführen (am schnellsten)

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

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

Die Umgebungsvariable MCP_TRANSPORT=stdio entspricht dem Parameter --stdio.

Methode 2: Aus dem Quellcode ausführen

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

Methode 3: Docker-Bereitstellung

Lokal erstellen und ausführen:

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

Methode 4: Remote-Server-Bereitstellung (öffentlicher Zugriff)

Geeignet, um den Dienst auf einem Cloud-Server bereitzustellen, damit MCP-Clients im LAN oder öffentlichen Netz eine Verbindung herstellen können.

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

Empfehlung: Prozessmanager für den dauerhaften Betrieb verwenden

# 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 verwenden (Client-Verbindung)

Claude Code (stdio-Modus, empfohlen)

Der Dienst muss nicht manuell gestartet werden; Claude Code startet den Prozess automatisch.

Methode 1: Projektweite .mcp.json-Konfiguration (empfohlen: Der Key folgt der Konfiguration und ist unabhängig von der .env im Startverzeichnis)

Im Projektstammverzeichnis eine .mcp.json erstellen:

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

Die Variablen im env-Block werden als Umgebungsvariablen an den Prozess übergeben und haben höhere Priorität als die .env-Datei (dotenv überschreibt bereits vorhandene Umgebungsvariablen nicht). Da .mcp.json den API-Key enthält, wird empfohlen, die Datei zur .gitignore hinzuzufügen, um ein Committen des Keys ins Repository zu vermeiden.

Methode 2: Per Befehlszeile registrieren

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

# 查看连接状态
claude mcp list

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

Claude Code (HTTP-Modus, lokal)

Zuerst den Dienst starten, dann registrieren:

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

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

Claude Code (HTTP-Modus, Remote-Server)

Wenn der Dienst auf einem Server bereitgestellt ist (z. B. http://192.168.1.100:30002/mcp), muss lokal kein Dienst gestartet werden:

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

Andere MCP-Clients (Claude Desktop / Cursor usw.)

stdio-Methode (claude_desktop_config.json von Claude Desktop):

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

HTTP-Methode (Clients, die HTTP unterstützen, wie Claude Desktop / Cursor):

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

Bei einem Remote-Server wird url durch die Serveradresse ersetzt.

API-Key über Request-Header übergeben (optional)

Wenn ZHIPU_API_KEY auf dem Server nicht konfiguriert ist, kann der Key in der Client-Konfiguration über headers übergeben werden (der Server verwendet bevorzugt den Key aus dem Request-Header):

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

Per Befehlszeile (Claude Code):

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

Hinweis: ZHIPU_API_KEY ist der Name des HTTP-Request-Headers. Der Node-Server liest ihn in Kleinbuchstaben als zhipu_api_key; der Client sendet ihn einfach unverändert.

Tool: analyze_image

Unterstützte lokale Bildformate: png / jpg / jpeg / webp / gif.

Häufig gestellte Fragen

1. Keine Verbindung möglich / Fehler ECONNREFUSED

Der Dienst wurde nicht gestartet oder der Port ist falsch. Stellen Sie sicher, dass zuerst npx glm4v-mcp (oder der Docker-Container) ausgeführt wird und MCP_PORT mit dem Port der registrierten URL übereinstimmt.

2. Aufruf liefert 401

ZHIPU_API_KEY fehlt oder ist ungültig. Prüfen Sie, ob beim Start des Dienstes die .env-Datei geladen wurde (der Dienst muss in einem Verzeichnis gestartet werden, das .env enthält), oder setzen Sie den Key direkt über eine Umgebungsvariable.

3. Der Dienst muss in Betrieb bleiben

Im HTTP-Transportmodus verbindet sich der Client in Echtzeit über den Port. Sobald der Dienstprozess stoppt, ist das Tool sofort nicht mehr verfügbar. Verwenden Sie in der Produktion pm2 / systemd / Docker, um den Dienst dauerhaft laufen zu lassen.

4. Key wird im stdio-Modus nicht geladen

Im stdio-Modus wird der Prozess vom Client gestartet (z. B. npx); die .env-Datei muss sich im Startverzeichnis des Clients befinden. Der sicherste Ansatz: ZHIPU_API_KEY direkt im env-Block der Client-Konfiguration (.mcp.json / claude_desktop_config.json) angeben (siehe Beispiel oben). Der Key folgt dann der Konfiguration und ist unabhängig vom Startverzeichnis.

5. Remote-Zugriff meldet Timeout

Stellen Sie sicher, dass die Sicherheitsgruppe/Firewall des Cloud-Servers den entsprechenden Port freigegeben hat und der Client den Server anpingen kann.

Lizenz

MIT