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-sonnetanthropic/claude-3-opusanthropic/claude-3-sonnetopenai/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
테스트 실행
릴리스 프로세스
이 프로젝트에서는 자동화된 릴리스 프로세스를 사용합니다.
- 의미적 버전 관리 원칙에 따라
pyproject.toml 의 버전을 업데이트합니다.- 도우미 스크립트를 사용할 수 있습니다:
python scripts/bump_version.py [major|minor|patch]
- 새 버전에 대한 세부 정보로
CHANGELOG.md 업데이트하세요.- 스크립트는 또한 CHANGELOG.md에 채울 수 있는 템플릿 항목을 생성합니다.
- 이러한 변경 사항을
main 브랜치에 커밋하고 푸시합니다. - GitHub Actions 워크플로는 다음과 같습니다.
- 버전 변경 감지
- 자동으로 새로운 GitHub 릴리스를 생성합니다
- PyPI에 게시하는 게시 워크플로를 트리거합니다.
이러한 자동화는 일관된 릴리스 프로세스를 유지하는 데 도움이 되며 모든 릴리스가 적절하게 버전 관리되고 문서화되도록 보장합니다.
지원하다
이 프로젝트가 도움이 된다면, 지속적인 개발과 유지 관리를 지원하기 위해 커피 한 잔 사주세요.
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.