MCP 오픈비전

개요

MCP OpenVision은 OpenRouter 비전 모델을 기반으로 이미지 분석 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. AI 어시스턴트가 MCP 생태계 내의 간단한 인터페이스를 통해 이미지를 분석할 수 있도록 지원합니다.

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 mcp-openvision을 자동으로 설치하려면:

지엑스피1

pip 사용하기

pip install mcp-openvision

UV 사용(권장)

uv pip install mcp-openvision

구성

MCP OpenVision에는 OpenRouter API 키가 필요하며 환경 변수를 통해 구성할 수 있습니다.

OPENROUTER_API_KEY (필수): OpenRouter API 키
OPENROUTER_DEFAULT_MODEL (선택 사항): 사용할 비전 모델

OpenRouter 비전 모델

MCP OpenVision은 비전 기능을 지원하는 모든 OpenRouter 모델과 호환됩니다. 기본 모델은 qwen/qwen2.5-vl-32b-instruct:free 이지만, 다른 호환 모델을 지정할 수 있습니다.

OpenRouter를 통해 제공되는 몇 가지 인기 있는 비전 모델은 다음과 같습니다.

qwen/qwen2.5-vl-32b-instruct:free (기본값)
anthropic/claude-3-5-sonnet
anthropic/claude-3-opus
anthropic/claude-3-sonnet
openai/gpt-4o

OPENROUTER_DEFAULT_MODEL 환경 변수를 설정하거나 model 매개변수를 image_analysis 함수에 직접 전달하여 사용자 정의 모델을 지정할 수 있습니다.

용법

MCP Inspector로 테스트

MCP OpenVision을 테스트하는 가장 쉬운 방법은 MCP Inspector 도구를 사용하는 것입니다.

npx @modelcontextprotocol/inspector uvx mcp-openvision

Claude Desktop 또는 Cursor와의 통합

MCP 구성 파일을 편집하세요.
- 윈도우: %USERPROFILE%\.cursor\mcp.json
- macOS: ~/.cursor/mcp.json 또는 ~/Library/Application Support/Claude/claude_desktop_config.json
다음 구성을 추가합니다.

{
  "mcpServers": {
    "openvision": {
      "command": "uvx",
      "args": ["mcp-openvision"],
      "env": {
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "OPENROUTER_DEFAULT_MODEL": "anthropic/claude-3-sonnet"
      }
    }
  }
}

개발을 위한 지역적 실행

# Set the required API key
export OPENROUTER_API_KEY="your_api_key"

# Run the server module directly
python -m mcp_openvision

특징

MCP OpenVision은 다음과 같은 핵심 도구를 제공합니다.

image_analysis : 다양한 매개변수를 지원하는 비전 모델로 이미지를 분석합니다.
- image : 다음과 같이 제공될 수 있습니다.
  - Base64로 인코딩된 이미지 데이터
  - 이미지 URL(http/https)
  - 로컬 파일 경로
- query : 이미지 분석 작업에 대한 사용자 지침
- system_prompt : 모델의 역할과 동작을 정의하는 지침(선택 사항)
- model : 사용할 비전 모델
- temperature : 무작위성 제어(0.0-1.0)
- max_tokens : 최대 응답 길이

효과적인 쿼리 작성

query 매개변수는 이미지 분석에서 유용한 결과를 얻는 데 매우 중요합니다. 잘 작성된 쿼리는 다음에 대한 맥락을 제공합니다.

목적 : 이 이미지를 분석하는 이유
집중 영역 : 주의해야 할 특정 요소 또는 세부 사항
필수 정보 : 추출해야 하는 정보의 종류
형식 기본 설정 : 결과를 어떻게 구성할지 선택합니다.

효과적인 쿼리의 예

기본 쿼리	향상된 쿼리
"이 이미지를 설명하세요"	"이 매장 선반 이미지에 보이는 모든 소매 제품을 식별하고 가격 범위를 추정하세요"
"이 사진에는 무엇이 들어있나요?"	"이 의료 스캔을 분석하여 이상 여부를 확인하고 강조된 영역에 초점을 맞춰 가능한 진단을 제공합니다."
"이 차트를 분석하세요"	"분기별 매출을 보여주는 이 막대형 차트에서 수치 데이터를 추출하고 2022-2023년의 주요 추세를 파악하세요."
"텍스트를 읽어보세요"	"이 레스토랑 메뉴에 표시된 모든 텍스트를 항목 이름, 설명 및 가격을 그대로 유지한 채 기록합니다."

분석이 필요한 이유와 구체적으로 어떤 정보를 찾고 있는지에 대한 맥락을 제공하면 모델이 관련 세부 정보에 집중하고 더욱 가치 있는 통찰력을 얻는 데 도움이 됩니다.

사용 예

# Analyze an image from a URL
result = await image_analysis(
    image="https://example.com/image.jpg",
    query="Describe this image in detail"
)

# Analyze an image from a local file with a focused query
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="Identify all traffic signs in this street scene and explain their meanings for a driver education course"
)

# Analyze with a base64-encoded image and a specific analytical purpose
result = await image_analysis(
    image="SGVsbG8gV29ybGQ=...",  # base64 data
    query="Examine this product packaging design and highlight elements that could be improved for better visibility and brand recognition"
)

# Customize the system prompt for specialized analysis
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="Analyze the composition and artistic techniques used in this painting, focusing on how they create emotional impact",
    system_prompt="You are an expert art historian with deep knowledge of painting techniques and art movements. Focus on formal analysis of composition, color, brushwork, and stylistic elements."
)

이미지 입력 유형

image_analysis 도구는 여러 유형의 이미지 입력을 허용합니다.

Base64로 인코딩된 문자열
이미지 URL - http:// 또는 https://로 시작해야 합니다.
파일 경로 :
- 절대 경로 : /(Unix) 또는 드라이브 문자(Windows)로 시작하는 전체 경로
- 상대 경로 : 현재 작업 디렉토리를 기준으로 한 경로
- project_root를 사용한 상대 경로 : project_root 매개변수를 사용하여 기본 디렉토리를 지정합니다.

상대 경로 사용

상대 파일 경로(예: "examples/image.jpg")를 사용하는 경우 두 가지 옵션이 있습니다.

경로는 서버가 실행 중인 현재 작업 디렉토리를 기준으로 해야 합니다.
또는 project_root 매개변수를 지정할 수 있습니다.

# Example with relative path and project_root
result = await image_analysis(
    image="examples/image.jpg",
    project_root="/path/to/your/project",
    query="What is in this image?"
)

이 기능은 현재 작업 디렉토리를 예측할 수 없는 애플리케이션이나 특정 디렉토리에 대한 상대 경로를 사용하여 파일을 참조하려는 경우에 특히 유용합니다.

개발

개발 환경 설정

# Clone the repository
git clone https://github.com/modelcontextprotocol/mcp-openvision.git
cd mcp-openvision

# Install development dependencies
pip install -e ".[dev]"

코드 포맷팅

이 프로젝트에서는 자동 코드 서식 지정을 위해 Black을 사용합니다. 서식은 GitHub Actions를 통해 적용됩니다.

저장소에 푸시된 모든 코드는 자동으로 Black으로 포맷됩니다.
저장소 협력자의 풀 리퀘스트에 대해 Black은 코드를 포맷하고 PR 브랜치에 직접 커밋합니다.
포크의 풀 리퀘스트에 대해 Black은 원본 PR에 병합될 수 있는 포맷된 코드로 새 PR을 생성합니다.

커밋하기 전에 코드를 포맷하기 위해 Black을 로컬로 실행할 수도 있습니다.

# Format all Python code in the src and tests directories
black src tests

테스트 실행

pytest

릴리스 프로세스

이 프로젝트에서는 자동화된 릴리스 프로세스를 사용합니다.

의미적 버전 관리 원칙에 따라 pyproject.toml 의 버전을 업데이트합니다.
- 도우미 스크립트를 사용할 수 있습니다: python scripts/bump_version.py [major|minor|patch]
새 버전에 대한 세부 정보로 CHANGELOG.md 업데이트하세요.
- 스크립트는 또한 CHANGELOG.md에 채울 수 있는 템플릿 항목을 생성합니다.
이러한 변경 사항을 main 브랜치에 커밋하고 푸시합니다.
GitHub Actions 워크플로는 다음과 같습니다.
- 버전 변경 감지
- 자동으로 새로운 GitHub 릴리스를 생성합니다
- PyPI에 게시하는 게시 워크플로를 트리거합니다.

이러한 자동화는 일관된 릴리스 프로세스를 유지하는 데 도움이 되며 모든 릴리스가 적절하게 버전 관리되고 문서화되도록 보장합니다.

지원하다

이 프로젝트가 도움이 된다면, 지속적인 개발과 유지 관리를 지원하기 위해 커피 한 잔 사주세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

mcp-openvision

Integrations