visionMCP 👁️

더 큰 추론 LLM의 눈.

visionMCP는 Model Context Protocol 서버로, MCP를 지원하는 모든 에이전트에게 실제 시각을 제공합니다. 텍스트 전용 추론 모델은 자신이 볼 수 없는 모든 것을 이 서버에 위임할 수 있습니다: 스크린샷 설명, 사진에 대한 질문 응답, 문서 OCR, 두 이미지 비교 등 — 서버가 시각을 담당하고 텍스트를 반환합니다.

단일 config.json에서 런타임에 선택되는 세 가지 주요 비전 백엔드 모두에서 작동합니다:

Features

• 🔍 추론 LLM이 호출할 네 가지 비전 도구:

  • describe_image — 전체 자연어 설명

  • ask_about_image — 모든 이미지에 대한 대상 질의응답

  • extract_text — OCR / 텍스트 변환

  • compare_images — 나란히 비교

• 🖼️ 모든 소스 허용: 로컬 파일 경로, http(s) URL, base64 data: URI.

• 📦 이미지 준비 불필요: 과도하게 큰 이미지는 자동으로 축소되고 JPEG으로 재인코딩되어 제공자 페이로드 제한에 맞춰집니다.

• 🔌 세 가지 전송 방식: stdio (기본값, 로컬 MCP 클라이언트용), http (원격 호스팅용 스트리밍 가능 HTTP), 또는 sse (레거시 서버 전송 이벤트).

• ⚙️ **하나의 config.json**이 제공자, API 키, API URL, 모델을 제어합니다. 환경 변수와 CLI 플래그로 모든 것을 재정의할 수 있습니다.

• 🚀 uv로 관리, 설치, 실행, 호스팅 가능.

Related MCP server: depu-img-mcp

Quick start

1. Install

uv와 Python ≥ 3.10이 필요합니다.

cd visionMCP
uv sync

2. Configure

제공된 config.json은 이미 로컬 Ollama에서 작동합니다. 파일을 편집하여 제공자를 전환하세요:

// config.json
{
  "provider": "openai",                  // "ollama" | "openai" | "anthropic"
  "api_key": "sk-...",                   // or leave "" and export OPENAI_API_KEY
  "api_url": "",                         // "" = provider default
  "model": ""                            // "" = provider default
}

모든 옵션은 docs/configuration.md를, 제공자별 설정은 docs/providers.md를 참조하세요.

보안: 실제 API 키는 git에 포함하지 마세요 — config.json을 config.local.json으로 복사하거나(자동 무시됨) 환경 변수를 사용하세요. 서버는 키를 절대 로그에 기록하지 않습니다.

3. Run

uv run vision-mcp                        # stdio transport (default)
uv run vision-mcp --transport http --host 0.0.0.0 --port 8100   # host remotely
uv run vision-mcp --show-config          # print resolved config (key masked)

Wiring into an MCP client

opencode (opencode.json)

{
  "mcpServers": {
    "visionMCP": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/visionMCP", "vision-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "visionMCP": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/visionMCP", "vision-mcp"]
    }
  }
}

Generic MCP client (stdio)

{
  "mcpServers": {
    "visionMCP": {
      "command": "/path/to/visionMCP/.venv/bin/vision-mcp",
      "args": ["--config", "/path/to/visionMCP/config.json"]
    }
  }
}

서버는 도구 호출이 제공하는 것 이상으로 이미지 콘텐츠를 비전 API에 전송하지 않습니다. 이미지 바이트는 메모리에 보관되며 디스크에 기록되지 않습니다.

Tools reference

image 인수는 다음 중 하나를 허용합니다:

/path/to/photo.png          # local file
https://example.com/x.jpg   # URL (downloaded at call time)
data:image/png;base64,iVBORw0KGgo...   # base64 data URI

How it works

모든 것은 src/vision_mcp/pipeline.py의 하나의 함수를 통해 전달됩니다:

image (path / URL / data URI)  →  base64 + mime  →  vision model  →  text
        _read()                     _encode()         API[provider]    look()

서버 도구는 얇은 래퍼입니다: pipeline.look(cfg, [image], prompt).

Documentation

• Configuration reference — 모든 구성 옵션, 환경 변수 및 우선순위 규칙

• Provider setup — Ollama, OpenAI, Anthropic 단계별 설정

• Deployment — HTTP/SSE를 통한 호스팅, Docker, 보안 강화

Development

uv sync --group dev
uv run ruff check .
uv run pytest

License

MIT