glm4v-mcp

Инкапсулирует визуальную модель GLM-4V от Zhipu в сервер 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-клиенты из локальной сети или интернета

Related MCP server: Look At Pic MCP

Требования к окружению

• Node.js ≥ 20

• API-ключ Zhipu (получить на портале разработчика), модель по умолчанию glm-4v-flash

Настройка API-ключа

Выберите один из трёх способов (приоритет: заголовок запроса > переменная окружения > .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: Развёртывание на удалённом сервере (доступ из интернета)

Подходит для размещения сервиса на облачном сервере, чтобы 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_config.json для Claude Desktop):

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

Режим http (клиенты, поддерживающие HTTP, такие как Claude Desktop / Cursor):

{
  "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.js читает его как 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 клиент подключается к порту в реальном времени; при остановке сервиса инструмент сразу становится недоступен. В production используйте pm2 / systemd / Docker для постоянной работы.

4. В режиме stdio ключ не загружается Процесс в режиме stdio запускается клиентом (например, npx), поэтому .env должен находиться в каталоге запуска клиента. Самый надёжный способ: указать ZHIPU_API_KEY непосредственно в блоке env конфигурации клиента (.mcp.json / claude_desktop_config.json) — как в примерах выше; ключ привязан к конфигурации и не зависит от каталога запуска.

5. Удалённый доступ — тайм-аут Убедитесь, что группа безопасности / брандмауэр облачного сервера разрешают нужный порт, и что клиент может ping сервер.

Лицензия

MIT