glm4v-mcp

Envuelve el modelo de visión GLM-4V de Zhipu como un servidor MCP, permitiendo analizar imágenes (rutas de archivo local o Data URL) mediante la herramienta analyze_image.

• Publicado en npm: glm4v-mcp

• Utiliza el protocolo estándar Model Context Protocol, compatible con cualquier cliente que soporte MCP

Características

• 🖼️ Análisis de imágenes: herramienta analyze_image, compatible con rutas de archivo local y Data URL

• 🧠 Modelo de visión GLM-4V: por defecto glm-4v-flash (gratuito), se puede cambiar mediante variables de entorno

• 🔌 Dos modos de transporte: stdio (proceso iniciado directamente, recomendado) y http (Streamable HTTP, compatible con implementación remota)

• 🌐 Acceso remoto: tras implementar en modo HTTP en un servidor, puede ser conectado por clientes MCP en la red local o pública

Related MCP server: Look At Pic MCP

Requisitos del entorno

• Node.js ≥ 20

• Clave API de Zhipu (solicitar en la plataforma abierta), modelo por defecto glm-4v-flash

Configurar la clave API

Elige una de las tres formas (prioridad: encabezado de solicitud > variable de entorno > .env):

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

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

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

Resumen de variables de entorno

Formas de implementación

Forma 1: Ejecutar directamente con npx (la más rápida)

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

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

La variable de entorno MCP_TRANSPORT=stdio equivale al parámetro --stdio.

Forma 2: Ejecutar desde el código fuente

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

Forma 3: Implementación con Docker

Construir y ejecutar localmente:

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

Forma 4: Implementación en servidor remoto (acceso público)

Adecuado para implementar el servicio en un servidor en la nube, permitiendo conexiones desde clientes MCP en la red local o pública.

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

Se recomienda usar un administrador de procesos para mantener el servicio en funcionamiento permanente

# 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

Uso con MCP (conexión del cliente)

Claude Code (modo stdio, recomendado)

No es necesario iniciar el servicio manualmente, Claude Code lo iniciará automáticamente.

Forma 1: Configuración a nivel de proyecto con .mcp.json (recomendado: la clave va con la configuración, no depende del .env del directorio de inicio)

Crear .mcp.json en la raíz del proyecto:

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

Las variables en el bloque env se pasan al proceso como variables de entorno, con prioridad sobre el archivo .env (dotenv no sobrescribe variables de entorno existentes). .mcp.json contiene la clave API, se recomienda agregarlo a .gitignore para evitar enviar la clave al repositorio.

Forma 2: Registrar desde la línea de comandos

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

# 查看连接状态
claude mcp list

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

Claude Code (modo http, local)

Primero iniciar el servicio, luego registrar:

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

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

Claude Code (modo http, servidor remoto)

Cuando el servicio está implementado en un servidor (ej. http://192.168.1.100:30002/mcp), no es necesario iniciar el servicio localmente:

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

Otros clientes MCP (Claude Desktop / Cursor, etc.)

Modo stdio (claude_desktop_config.json de Claude Desktop):

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

Modo http (clientes que soportan HTTP como Claude Desktop / Cursor):

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

Para servidor remoto, reemplazar url con la dirección del servidor.

Pasar la clave API a través del encabezado de solicitud (opcional)

Si el servidor no tiene configurada ZHIPU_API_KEY, se puede pasar a través de headers en la configuración del cliente (el servidor priorizará la clave del encabezado de solicitud):

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

Forma de línea de comandos (Claude Code):

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

Nota: ZHIPU_API_KEY es el nombre del encabezado HTTP, el servidor Node lo lee en minúsculas como zhipu_api_key, el cliente lo envía tal cual.

Herramienta: analyze_image

Formatos de imagen local compatibles: png / jpg / jpeg / webp / gif.

Preguntas frecuentes

1. No se puede conectar / error ECONNREFUSED El servicio no está iniciado o el puerto es incorrecto. Asegúrate de ejecutar primero npx glm4v-mcp (o el contenedor Docker) y que MCP_PORT coincida con el puerto registrado en la URL.

2. Error 401 al llamar ZHIPU_API_KEY falta o no es válida. Verifica si el archivo .env se cargó al iniciar el servicio (el servicio debe iniciarse en el directorio que contiene .env), o establece la variable de entorno directamente.

3. El servicio debe mantenerse en ejecución En modo de transporte HTTP, el cliente se conecta en tiempo real a través del puerto; si el proceso del servicio se detiene, la herramienta deja de estar disponible inmediatamente. En producción, usa pm2 / systemd / Docker para mantenerlo en funcionamiento permanente.

4. En modo stdio, la clave no se carga En modo stdio, el proceso es iniciado por el cliente (ej. npx), por lo que .env debe estar en el directorio de inicio del cliente. La forma más segura: escribir ZHIPU_API_KEY directamente en el bloque env de la configuración del cliente (.mcp.json / claude_desktop_config.json) (ver ejemplos anteriores); la clave va con la configuración, independientemente del directorio de inicio.

5. Tiempo de espera agotado al acceder de forma remota Verifica que el grupo de seguridad / firewall del servidor en la nube tenga habilitado el puerto correspondiente y que el cliente pueda hacer ping al servidor.

Licencia

MIT