vision-mcp

순수 텍스트 메인 모델에 시각 능력을 보완하는 경량 MCP 서버. 메인 모델이 이미지(스크린샷, UI 다이어그램, 플로우차트, 오류 스크린샷 등)를 만났지만 이해할 수 없을 때, MCP 도구를 통해 이미지를 OpenAI 호환 멀티모달 백엔드(Qwen-VL, GPT-4o, Gemini, 로컬 vLLM 등)에 넘겨 분석하고 텍스트 결과를 반환합니다.

主模型(纯文本) ──调用 MCP 工具──▶ vision-mcp ──Chat Completions──▶ 多模态模型
   Claude/Codex ◀──────文本结果───────◀──────────────────────────   Qwen-VL / GPT-4o / ...

빠른 시작

권장: 저장소에 포함된 bin/wrapper.sh로 바로 시작합니다. wrapper는 첫 호출 시 디렉터리에 .venv를 자동 생성하고 의존성을 설치합니다(uv 우선, uv가 없으면 venv+pip). 수동 설치가 필요 없으며, 이후 실제 server.py를 exec합니다. macOS / Linux에 적합합니다.

# 方式一（推荐，免手动装依赖）：MCP client 指向 wrapper 即可
claude mcp add vision-mcp -- /绝对/路径/vision-mcp/bin/wrapper.sh

# 或先自测：wrapper 会自举依赖并启动 server
/绝对/路径/vision-mcp/bin/wrapper.sh --check

Windows는 python -m venv + install.ps1을 사용하거나 python server.py를 직접 실행하세요.

Related MCP server: vision-mcp

설치(소스 직접 빌드)

먼저 MCP 서버 본체(Python)를 설치합니다:

# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1
# macOS / Linux
./install.sh

그런 다음 클라이언트에 맞게 연결합니다:

Claude Code

claude mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

Codex

codex mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

MCP 구성을 수정한 후 클라이언트를 재시작해야 적용됩니다.

pi

cp pi-extensions/vision-mcp.ts ~/.pi/agent/extensions/
# 依赖：typebox（必需，工具参数模式定义）；sharp（可选，图片缩放，未装则自动降级为不缩放）
cd ~/.pi/agent/extensions && npm i sharp typebox

복사 후 pi를 재시작하거나 /reload로 자동 로드되며 pi install이 필요 없습니다. pi 확장은 기능 게이팅을 지원합니다: 메인 모델이 이미지를 기본 지원(input에 image 포함)하면 세 가지 비전 도구를 자동으로 숨겨 불필요한 위임을 방지하고, 순수 텍스트 메인 모델에서만 표시됩니다.

구성

우선순위: config.json > 프로세스 환경 변수 > .env > 기본값. config.json은 gitignore 처리되어 저장소에 포함되지 않습니다.

cp config.example.json config.json   # 再编辑 api_key 等字段

{
  "api": "openai-completions",
  "api_key": "sk-your-dashscope-api-key",
  "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "model": "qwen-vl-plus",
  "max_tokens": 4096,
  "timeout": 120,
  "max_retries": 2,
  "retry_backoff": 2
}

pi 확장은 추가로 ~/.pi/vision-mcp/config.json을 읽습니다(또는 VISION_CONFIG_PATH로 지정). 키는 위와 동일합니다.

지원 형식: PNG / JPEG / WebP / GIF(BMP는 주요 비전 백엔드가 지원하지 않아 제외됨).

일반적인 백엔드: DashScope(기본) VISION_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1; OpenAI model=gpt-4o; 로컬 vLLM base_url=http://localhost:8000/v1.

구성 확인

# wrapper 方式（依赖未装则先自举）
./bin/wrapper.sh --check
# 源码自建（依赖手动安装后）
python server.py --check   # 打印生效配置，API key 脱敏

도구

• vision_analyze — 범용 이미지 이해. 매개변수: prompt(선택), image/image_path/image_url/image_base64(네 가지 중 하나).

• vision_ocr — 이미지의 텍스트를 문자 단위로 추출. 매개변수는 analyze와 동일(prompt 없음).

• vision_analyze_batch — 여러 장을 일괄 분석. 매개변수: items(필수, 각 항목은 네 가지 중 하나의 이미지 소스, prompt 포함 가능), prompt(선택), concurrency(기본 3, 범위 1-8).

오픈소스

소스 코드 형태로 공개되어 있으며 Fork / Issue / PR을 환영합니다.