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 Key (오픈 플랫폼에서 신청), 기본 모델 glm-4v-flash

API Key 설정

세 가지 방법 중 하나 선택 (우선순위: 요청 헤더 > 환경 변수 > .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 설정 (권장: 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가 저장소에 커밋되지 않도록 하는 것이 좋습니다.

방법 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 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

지원되는 로컬 이미지 형식: 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