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 モードでサーバーにデプロイすると、LAN/インターネット上の MCP クライアントから接続可能

Related MCP server: Look At Pic MCP

環境要件

• Node.js ≥ 20

• 智譜 API キー（オープンプラットフォームで申請）、モデルデフォルトは glm-4v-flash

API キーの設定

以下の3つの方法から選択（優先順位：リクエストヘッダー > 環境変数 > .env）：

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

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

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

環境変数一覧

デプロイ方法

方法1：npx で直接実行（最速）

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

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

MCP_TRANSPORT=stdio 環境変数は --stdio 引数と同等です。

方法2：ソースコードから実行

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

方法3：Docker デプロイ

ローカルでビルドして実行：

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

方法4：リモートサーバーへのデプロイ（インターネットアクセス）

サービスをクラウドサーバーにデプロイし、LAN またはインターネット上のデバイスから 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 が自動的にプロセスを起動します。

方法1：プロジェクトレベルの .mcp.json 設定（推奨：キーが設定と一緒に管理され、起動ディレクトリの .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 キーが含まれるため、.gitignore に追加してキーがリポジトリにコミットされないようにすることを推奨します。

方法2：コマンドラインで登録

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 キーを渡す（オプション）

サーバー側で ZHIPU_API_KEY が設定されていない場合、クライアント設定で headers を介して渡すことができます（サーバーはリクエストヘッダーのキーを優先して使用します）：

{
  "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

対応ローカル画像形式：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 モードでキーが読み込まれない stdio モードのプロセスはクライアント（例：npx）によって起動されるため、.env はクライアントの起動ディレクトリに配置する必要があります。最も確実な方法は、クライアント設定（.mcp.json / claude_desktop_config.json）の env ブロックに直接 ZHIPU_API_KEY を記述することです（上記の例を参照）。キーは設定と一緒に管理され、起動ディレクトリに依存しません。

5. リモートアクセスでタイムアウトになる クラウドサーバーのセキュリティグループ/ファイアウォールで該当ポートが開放されていること、およびクライアントからサーバーに ping が通ることを確認してください。

ライセンス

MIT