Vision MCP

시각 능력이 없는 LLM（예: GLM）도 Claude Code / Codex에서 이미지를 처리할 수 있게 합니다.

작동 원리

메인 모델이 이미지를 만나면 이 MCP가 제공하는 describe_image 도구를 호출합니다:

1. 도구가 로컬 이미지 파일을 읽습니다

2. 사용자가 구성한 비전 모델（Qwen-VL / GPT-4o / GLM-4V / Doubao 등 모든 OpenAI 호환 인터페이스）을 호출합니다

3. 텍스트 설명을 메인 모델에 반환합니다

4. 메인 모델은 텍스트를 기반으로 추론을 계속합니다

메인 모델은 전체 과정에서 이미지 바이너리를 접하지 않으므로 순수 텍스트 모델도 사용할 수 있습니다.

이 프로젝트는 타사 의존성이 전혀 없으며（순수 Python 표준 라이브러리）, Python 3.8+에서 실행할 수 있고 pip 설치가 필요 없습니다.

Related MCP server: Image-Vision MCP Server

원클릭 설치

git clone https://github.com/Ruiba0/Vision-MCP.git
cd vision-mcp
python3 install.py

Windows에는 python3 명령이 없으므로 python install.py를 사용하면 됩니다. 아래의 모든 python3도 마찬가지입니다.

설치 스크립트는 대화형으로 다음 작업을 수행합니다:

• 비전 모델의 base URL / 모델명 / API 키를 입력하도록 안내합니다（일반적인 공급자 참고 포함）

• MCP를 Claude Code에 등록합니다（claude mcp add）

• MCP를 Codex에 등록합니다（~/.codex/config.toml에 기록）

• ~/.claude/CLAUDE.md 및 ~/.codex/AGENTS.md에 이미지 처리 규칙을 추가합니다

스크립트는 멱등적이므로 반복 실행할 수 있습니다.

수동 설치

설치 스크립트를 사용하지 않으려면:

1. 비전 모델 구성

   config.example.json을 config.json으로 복사하고 비전 모델 구성을 입력하세요:

   {
     "vision_api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
     "vision_model": "qwen-vl-max",
     "vision_api_key": "sk-你的key",
     "max_image_bytes": 10485760
   }

2. Claude Code에 등록

   claude mcp add --scope user vision -- python3 /绝对路径/server.py

   --scope user를 추가하면 전역에서 사용할 수 있습니다（추가하지 않으면 현재 디렉터리에서만 적용됩니다）.

3. Codex에 등록

   ~/.codex/config.toml을 편집하고 다음을 추가하세요:

   [mcp_servers.vision]
   command = "python3"
   args = ["/绝对路径/server.py"]

4. 이미지 처리 규칙 추가

   ~/.claude/CLAUDE.md 및 ~/.codex/AGENTS.md에 다음 내용을 추가하세요（메인 모델이 이미지를 만나면 도구를 능동적으로 호출하도록 합니다）:

   ## 图片处理
   
   当用户提到图片文件路径（.png/.jpg/.jpeg/.gif/.webp/.bmp），或要求查看/分析/识别某个图片文件时：
   
   - 先判断当前主模型自身是否具备视觉能力
   - 具备视觉（如 Claude Sonnet/Opus、GPT-4o、Qwen-VL 等多模态模型）→ 直接读取图片并分析
   - 不具备视觉（如 GLM 等纯文本模型）→ 调用 vision MCP 的 describe_image 工具，传入图片路径和问题
   - 不确定自身是否支持视觉时，默认调用 describe_image 工具作为兜底
   - 用户明确要求"用 MCP 看"或"调视觉模型"时，无论主模型是否支持视觉，都调用 describe_image 工具

지원되는 비전 모델

OpenAI 프로토콜과 호환되는 모든 비전 모델을 사용할 수 있습니다:

Anthropic 네이티브 프로토콜（예: Claude）을 사용하려면 vision_client.py를 직접 수정해야 합니다. 현재는 OpenAI 호환 프로토콜만 지원합니다.

사용 방법

설치가 완료되면 Claude Code / Codex를 재시작하고 대화에서:

• "~/Desktop/diagram.png에서 이 이미지를 확인해 봐"

• "~/Screenshots/error.jpg에 있는 오류를 분석해 봐"

• "~/Documents/notes/page1.jpeg에서 모든 텍스트를 인식해 봐"

（Windows에서는 경로가 D:/temp/diagram.png와 같으니 시스템에 맞게 작성하면 됩니다）

메인 모델이 자동으로 describe_image 도구를 호출하고, 도구는 비전 모델의 텍스트 설명을 반환합니다. 메인 모델은 이 설명을 기반으로 답변을 이어갑니다.

도구 매개변수

describe_image(path: str, question: str = "详细描述这张图片的内容") -> str

• path: 이미지 파일의 절대 경로이며 png/jpg/jpeg/gif/webp/bmp를 지원합니다

• question: 비전 모델에게 묻고 싶은 질문이며 상황에 따라 조정할 수 있습니다（"텍스트 인식", "레이아웃 설명", "차트 분석" 등）

프로젝트 구조

vision-mcp/
├── server.py              # MCP 服务（内置 stdio JSON-RPC 实现，无 SDK 依赖）
├── vision_client.py       # 视觉模型调用（OpenAI 兼容协议，urllib 实现）
├── config.example.json    # 配置模板（提交到 git）
├── config.json            # 你的实际配置（gitignored）
├── install.py             # 一键安装脚本
└── README.md

자주 묻는 질문

Q: 호출 시 视觉模型连接失败 오류가 발생합니다 vision_api_base 경로가 올바른지 확인하세요. 도구는 base URL 뒤에 /chat/completions를 붙이므로 base URL에 /chat/completions 접미사를 포함하지 마세요.

Q: 호출 시 HTTP 401 오류가 발생합니다 API 키가 유효하지 않거나 해당 모델 권한이 없습니다. vision_api_key와 vision_model이 해당 플랫폼과 일치하는지 확인하세요.

Q: 메인 모델이 도구를 능동적으로 호출하지 않습니다 CLAUDE.md / AGENTS.md에 이미지 처리 규칙이 추가되었는지 확인하세요. 규칙의 키워드（이미지, 보기, 분석）는 메인 모델이 describe_image를 호출하도록 안내합니다.

Q: 비전 모델을 변경하고 싶습니다 config.json을 편집하여 세 필드만 수정하면 되며 코드는 변경할 필요가 없습니다. 또는 python3 install.py를 다시 실행하여 재구성하세요.

의존성

• Python 3.8+（순수 표준 라이브러리이며, pip로 패키지를 설치할 필요 없음）

License

MIT