glm-vision MCP Server

임의의 AI 에이전트에 '이미지 보기' 능력을 추가합니다. 내부적으로 智谱의 완전 무료 비전 추론 모델을 호출하고, MCP 프로토콜을 통해 표준 도구로 노출되므로 MCP를 지원하는 모든 클라이언트가 바로 사용할 수 있으며 API 비용이 전혀 없습니다.

💡 무료 보장: 전부 智谱 복지 전용의 무료 모델(GLM-4.6V-Flash / GLM-4.1V-Thinking-Flash / GLM-4V-Flash)만 사용하며, 유료 모델은 포함되지 않으므로 장기간 사용해도 비용이 발생하지 않습니다.

노출되는 도구

analyze_image(image_input, question, thinking)

반환: 모델이 출력한 텍스트 분석 결과.

특징

• 로컬 이미지는 자동으로 raw base64로 읽어 전송되므로 이미지 호스팅도, 공개 URL도 필요 없습니다

• 단일 이미지 5MB 상한 검증 (智谱 제한)

• 429 rate limit 발생 시 자동 백오프로 3회 재시도 (1.5s / 3s / 4.5s)

• 그래도 실패하면 자동으로 glm-4.6v-flash → glm-4.1v-thinking-flash → glm-4v-flash로 하향 조정 (전부 무료), 하향 조정 시 답변의 시작 부분에 어떤 모델을 사용했는지 표시합니다.

Related MCP server: Kimi Vision MCP Server

배포 3단계

1. 의존성 설치

pip install -r requirements.txt

⚠️ 핵심 함정: mcp는 반드시 1.x를 설치해야 합니다. 최신 mcp 2.0.0은 내장된 mcp.server.fastmcp 모듈을 제거했기 때문에 설치하면 바로 ImportError가 발생합니다. 따라서 pip install "mcp<2"입니다.

⚠️ 또 다른 함정: zai나 zhipuai를 설치하지 마세요. PyPI에서 이 두 이름은 관련 없는 자리 표시자 패키지입니다. (zai는 Zalando의 것이고, zhipuai는 임포트 이름이 변경되었습니다). 이 서버는 OpenAI 호환 클라이언트로 智谱 인터페이스(base_url=https://open.bigmodel.cn/api/paas/v4)에 직접 연결하므로 openai 패키지만 필요합니다.

2. API Key 설정

bigmodel.cn에서 휴대폰 번호로 가입 → 콘솔의 'API Keys'에서 새로 만들면 무료입니다.

Key를 지정하는 방법은 두 가지이며, 환경 변수의 우선순위가 더 높습니다:

• 방식 A (권장): 환경 변수 ZHIPU_API_KEY=你的key 설정

• 방식 B: zhipu_key.txt.example을 zhipu_key.txt로 이름을 바꾸고 Key를 입력합니다 (스크립트가 같은 디렉터리의 이 파일을 자동으로 읽습니다).

3. 클라이언트에 설정

클라이언트의 MCP 설정 파일에 한 부분을 추가합니다 (경로는 자신의 것으로 변경):

{
  "mcpServers": {
    "glm-vision": {
      "command": "python",
      "args": ["/绝对路径/到/glm_vision_mcp.py"],
      "env": {
        "ZHIPU_API_KEY": "你的key"
      }
    }
  }
}

command에는 Python 인터프리터의 절대 경로(예: D:/python/python.exe)를 쓰는 것이 좋습니다. 클라이언트 시작 시 PATH에서 python을 찾지 못하는 경우를 피하기 위해서입니다.

설정 완료 후 반드시 클라이언트를 재시작하세요 — MCP 프로세스는 클라이언트 시작 시에만 한 번 spawn되므로, 설정이나 코드를 변경해도 핫 리로드되지 않습니다.

성공 여부 확인

클라이언트를 재시작한 후 Agent에게 이미지 하나를 분석하라고 하면 됩니다:

D:\test.png 이 이미지에 뭐가 있는지 봐줘

Agent가 도구를 찾을 수 없다고 하면 다음을 확인하세요: 설정 파일 JSON 문법, 스크립트 절대 경로가 올바른지, 클라이언트를 재시작했는지, 클라이언트에서 이 서버를 수동으로 '신뢰/활성화'해야 하는지 (WorkBuddy와 Cursor 모두 이 단계가 있습니다).

일반적인 오류 대응

파일 목록