mcp-vision-server

모든 OpenAI 호환 비전 모델을 위한 단일 MCP 서버입니다.

한 번 구성하면 OpenAI, OpenRouter, Zhipu, Bailian, SiliconFlow 및 기타 호환 공급자에서 동일한 analyze_image 도구를 사용할 수 있습니다. Claude Code, Codex, Cursor, Zed 및 기타 MCP 클라이언트에서 작동합니다.

mcp-vision-server를 사용하는 이유는 무엇인가요?

• ✅ 모든 MCP 클라이언트와 호환 – Claude Code, Codex, Cursor, Zed 등.

• ✅ 다양한 공급자 지원 – 프롬프트나 도구 호출을 변경하지 않고 공급자를 전환할 수 있습니다.

• ✅ 단일 통합 API – 모든 OpenAI 호환 비전 엔드포인트를 위한 하나의 도구(analyze_image).

• ✅ 유연한 이미지 입력 – URL, 로컬 파일 또는 Base64가 자동으로 감지됩니다.

• ✅ 어디서나 재정의 – 환경 변수로 전역 구성하거나 요청별로 구성할 수 있습니다.

Related MCP server: vision-mcp

빠른 시작

1. 서버를 설치합니다.

2. 공급자와 API 키를 설정합니다.

3. MCP 서버를 클라이언트에 추가합니다.

4. 질문합니다:

Describe this screenshot.

모든 것이 올바르게 구성되면 MCP 클라이언트가 자동으로 analyze_image를 호출하고 비전 모델의 응답을 반환합니다.

기능

• 일관된 인터페이스를 갖춘 단일 analyze_image 도구.

• URL, 로컬 파일 및 Base64 이미지 입력 지원.

• 13개의 내장 공급자 사전 설정 지원.

• VISION_PROVIDER 또는 provider 매개변수를 통한 공급자 선택.

• 환경 수준 및 요청 수준 구성 재정의.

예시

MCP 클라이언트에 이미지 분석을 요청합니다:

Analyze this screenshot and tell me what UI is shown.

클라이언트가 MCP 도구를 호출합니다:

{
  "tool": "analyze_image",
  "arguments": {
    "image": "/path/to/screenshot.png",
    "prompt": "Analyze this screenshot and tell me what UI is shown."
  }
}

서버가 이미지 입력을 정규화하고 선택한 OpenAI 호환 비전 공급자에게 전송한 후 일반 텍스트 응답을 MCP 클라이언트에 반환합니다.

공급자

내장 사전 설정으로 일반적인 OpenAI 호환 비전 엔드포인트를 쉽게 사용할 수 있습니다:

VISION_BASE_URL, VISION_API_KEY 및 VISION_MODEL을 수동으로 설정하여 다른 OpenAI 호환 비전 엔드포인트를 사용할 수도 있습니다.

설치 및 실행

Python ≥ 3.10 및 uv가 필요합니다.

cd mcp-vision-server
uv sync                  # install deps
uv run pytest -v         # run tests
uv run ruff check .      # lint
uv run mcp-vision-server # start stdio server

구성

옵션 1: 공급자 사전 설정 (권장)

export VISION_PROVIDER=zhipu     # default
export VISION_API_KEY=your_key

전체 사전 설정 목록은 공급자를 참조하세요.

대체 수단으로 공급자별 환경 변수(예: DASHSCOPE_API_KEY, OPENAI_API_KEY)를 사용할 수도 있습니다.

옵션 2: 수동

도구 매개변수(호출별 환경 재정의): image, prompt, image_type, provider, base_url, api_key, model, temperature, max_tokens.

MCP 클라이언트 설정

Claude Code (.mcp.json)

{
  "mcpServers": {
    "vision": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-vision-server", "mcp-vision-server"],
      "env": {
        "VISION_PROVIDER": "zhipu",
        "VISION_API_KEY": "your_key"
      }
    }
  }
}

Claude Code 플러그인

# After PyPI publish
claude plugins install RuyimgByCN/mcp-vision-server

# Local test
claude plugins install /path/to/mcp-vision-server

저장소에는 .claude-plugin.json 매니페스트가 포함되어 있습니다. claude plugins install이 자동으로 읽습니다.

Codex (OpenAI Codex CLI)

~/.codex/config.toml을 편집하세요:

[mcp_servers.vision]
command = "uvx"
args = ["mcp-vision-server"]
env = { VISION_PROVIDER = "zhipu", VISION_API_KEY = "your_key" }

또는 로컬 개발의 경우:

[mcp_servers.vision]
command = "uv"
args = ["run", "--directory", "/path/to/mcp-vision-server", "mcp-vision-server"]
env = { VISION_PROVIDER = "zhipu", VISION_API_KEY = "your_key" }

Cursor / 기타 uvx 클라이언트

command를 uvx로, args를 ["--from", "/path/to/mcp-vision-server", "mcp-vision-server"]로 바꾸고 env는 동일하게 유지하세요.

공급자 예시

// Bailian
"env": { "VISION_PROVIDER": "bailian", "VISION_API_KEY": "your_key" }

// OpenAI
"env": { "VISION_PROVIDER": "openai", "VISION_API_KEY": "sk-xxx" }

// Fully custom
"env": {
  "VISION_BASE_URL": "https://your-endpoint/v1",
  "VISION_API_KEY": "your_key",
  "VISION_MODEL": "your-model"
}

아키텍처

MCP Client (Claude Code / Codex / Cursor / Zed)
        │
        ▼
mcp-vision-server
        │
        ├── mcp_vision_server/server.py     # MCP tool entrypoints
        ├── mcp_vision_server/config.py     # env/provider/parameter resolution
        ├── mcp_vision_server/image.py      # URL/file/base64 normalization
        └── mcp_vision_server/providers.py  # provider presets
        │
        ▼
OpenAI-compatible Vision API
        │
        ▼
Vision model response

자주 묻는 질문

비전 공급자를 직접 호출하지 않는 이유는 무엇인가요?

이 서버는 MCP 클라이언트에 단일하고 재사용 가능한 비전 도구를 제공합니다. 클라이언트 프롬프트, MCP 도구 이름 또는 클라이언트 측 통합 코드를 변경하지 않고 공급자를 전환할 수 있습니다.

목록에 없는 공급자를 사용할 수 있나요?

예. 모든 OpenAI 호환 비전 엔드포인트에 대해 VISION_BASE_URL, VISION_API_KEY 및 VISION_MODEL을 사용한 수동 구성을 사용하세요.

요청별로 공급자를 재정의할 수 있나요?

예. provider, base_url, api_key 또는 model 도구 매개변수를 사용하여 단일 호출에 대한 환경 수준 구성을 재정의할 수 있습니다.

어떤 이미지 형식이 지원되나요?

서버는 이미지 URL, 로컬 파일 경로 및 Base64 문자열을 허용합니다. 입력 유형은 자동 감지되거나 image_type으로 지정할 수 있습니다.

개발

uv sync --all-groups
uv run ruff check .
uv run ruff format .
uv run pytest -v
uv build
uv run twine check dist/*

릴리스 체크리스트

1. pyproject.toml의 버전을 업데이트합니다.

2. uv run ruff check ., uv run pytest -v, uv build 및 uv run twine check dist/*를 실행합니다.

3. 예를 들어 v0.1.2와 같은 버전 태그를 만들고 푸시합니다.

4. GitHub Actions가 신뢰할 수 있는 게시를 통해 PyPI에 게시하도록 합니다.

로드맵

• 안정적인 OpenAI 호환 비전 엔드포인트를 사용할 수 있게 되면 더 많은 공급자 사전 설정을 추가합니다.

• Claude Code, Codex, Cursor 및 기타 MCP 클라이언트에 대한 더 풍부한 예제를 추가합니다.

• MCP 클라이언트 UX에 도움이 되는 경우 선택적 스트리밍 응답 지원을 추가합니다.

• 공급자가 사용자 지정 요청 로직을 요구하는 경우에만 공급자별 동작을 플러그인으로 분리합니다.

정보

저자: RuyimgByCN

라이선스: 개인용으로만 사용할 수 있습니다. 상업적 사용은 금지됩니다. 자세한 내용은 LICENSE를 참조하세요. 상업용 라이선스는 저자에게 문의하세요.

中文说明： 个人使用免费，禁止商用。商业授权请联系作者。详见 README_ZH.md。