Skip to main content
Glama
enesjakozh
Nazruden

mcp-openvision

by Nazruden
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

MCP 오픈비전

씨아이 PyPI 버전 파이썬 버전 라이센스: MIT 나에게 커피 한 잔 사줘 대장간 배지

개요

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

Related MCP server: MCP OpenVision

설치

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와의 통합

  1. MCP 구성 파일을 편집하세요.

    • 윈도우: %USERPROFILE%\.cursor\mcp.json

    • macOS: ~/.cursor/mcp.json 또는 ~/Library/Application Support/Claude/claude_desktop_config.json

  2. 다음 구성을 추가합니다.

{
  "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 매개변수는 이미지 분석에서 유용한 결과를 얻는 데 매우 중요합니다. 잘 작성된 쿼리는 다음에 대한 맥락을 제공합니다.

  1. 목적 : 이 이미지를 분석하는 이유

  2. 집중 영역 : 주의해야 할 특정 요소 또는 세부 사항

  3. 필수 정보 : 추출해야 하는 정보의 종류

  4. 형식 기본 설정 : 결과를 어떻게 구성할지 선택합니다.

효과적인 쿼리의 예

기본 쿼리

향상된 쿼리

"이 이미지를 설명하세요"

"이 매장 선반 이미지에 보이는 모든 소매 제품을 식별하고 가격 범위를 추정하세요"

"이 사진에는 무엇이 들어있나요?"

"이 의료 스캔을 분석하여 이상 여부를 확인하고 강조된 영역에 초점을 맞춰 가능한 진단을 제공합니다."

"이 차트를 분석하세요"

"분기별 매출을 보여주는 이 막대형 차트에서 수치 데이터를 추출하고 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 도구는 여러 유형의 이미지 입력을 허용합니다.

  1. Base64로 인코딩된 문자열

  2. 이미지 URL - http:// 또는 https://로 시작해야 합니다.

  3. 파일 경로 :

    • 절대 경로 : /(Unix) 또는 드라이브 문자(Windows)로 시작하는 전체 경로

    • 상대 경로 : 현재 작업 디렉토리를 기준으로 한 경로

    • project_root를 사용한 상대 경로 : project_root 매개변수를 사용하여 기본 디렉토리를 지정합니다.

상대 경로 사용

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

  1. 경로는 서버가 실행 중인 현재 작업 디렉토리를 기준으로 해야 합니다.

  2. 또는 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

릴리스 프로세스

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

  1. 의미적 버전 관리 원칙에 따라 pyproject.toml 의 버전을 업데이트합니다.

    • 도우미 스크립트를 사용할 수 있습니다: python scripts/bump_version.py [major|minor|patch]

  2. 새 버전에 대한 세부 정보로 CHANGELOG.md 업데이트하세요.

    • 스크립트는 또한 CHANGELOG.md에 채울 수 있는 템플릿 항목을 생성합니다.

  3. 이러한 변경 사항을 main 브랜치에 커밋하고 푸시합니다.

  4. GitHub Actions 워크플로는 다음과 같습니다.

    • 버전 변경 감지

    • 자동으로 새로운 GitHub 릴리스를 생성합니다

    • PyPI에 게시하는 게시 워크플로를 트리거합니다.

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

지원하다

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

특허

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

Available Tools

1 tool
image_analysisA
Analyze an image using OpenRouter's vision capabilities.

This tool allows you to send an image to OpenRouter's vision models for analysis.
You provide a query to guide the analysis and can optionally customize the system prompt
for more control over the model's behavior.

Args:
    image: The image as a base64-encoded string, URL, or local file path
    query: Text prompt to guide the image analysis. For best results, provide context
           about why you're analyzing the image and what specific information you need.
           Including details about your purpose and required focus areas leads to more
           relevant and useful responses.
    system_prompt: Instructions for the model defining its role and behavior
    model: The vision model to use (defaults to the value set by OPENROUTER_DEFAULT_MODEL)
    max_tokens: Maximum number of tokens in the response (100-4000)
    temperature: Temperature parameter for generation (0.0-1.0)
    top_p: Optional nucleus sampling parameter (0.0-1.0)
    presence_penalty: Optional penalty for new tokens based on presence in text so far (0.0-2.0)
    frequency_penalty: Optional penalty for new tokens based on frequency in text so far (0.0-2.0)
    project_root: Optional root directory to resolve relative image paths against

Returns:
    The analysis result as text

Examples:
    Basic usage with a file path:
        image_analysis(image="path/to/image.jpg", query="Describe this image in detail")

    Basic usage with an image URL:
        image_analysis(image="https://example.com/image.jpg", query="Describe this image in detail")

    Basic usage with a relative path and project root:
        image_analysis(image="examples/image.jpg", project_root="/path/to/project", query="Describe this image in detail")

    Usage with a detailed contextual query:
        image_analysis(
            image="path/to/image.jpg",
            query="Analyze this product packaging design for a fitness supplement. Identify all nutritional claims,
                  certifications, and health icons. Assess the visual hierarchy and how the key selling points
                  are communicated. This is for a competitive analysis project."
        )

    Usage with custom system prompt:
        image_analysis(
            image="path/to/image.jpg",
            query="What objects can you see in this image?",
            system_prompt="You are an expert at identifying objects in images. Focus on listing all visible objects."
        )
ParametersJSON Schema
NameRequiredDescriptionDefault
imageYes
queryNoDescribe this image in detail
system_promptNoYou are an expert vision analyzer with exceptional attention to detail. Your purpose is to provide accurate, comprehensive descriptions of images that help AI agents understand visual content they cannot directly perceive. Focus on describing all relevant elements in the image - objects, people, text, colors, spatial relationships, actions, and context. Be precise but concise, organizing information from most to least important. Avoid making assumptions beyond what's visible and clearly indicate any uncertainty. When text appears in images, transcribe it verbatim within quotes. Respond only with factual descriptions without subjective judgments or creative embellishments. Your descriptions should enable an agent to make informed decisions based solely on your analysis.
modelNo
max_tokensNo
temperatureNo
top_pNo
presence_penaltyNo
frequency_penaltyNo
project_rootNo

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden for behavioral disclosure. It explains that the tool uses OpenRouter's vision models and returns text, and it lists default parameter values. However, it lacks information about external API dependencies, potential latency, failure modes, or rate limits, which are important for an agent to understand. The description is adequate but not comprehensive in this regard.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear introductory sentence, parameter list, return value, and examples. While it is verbose in parts (e.g., the query parameter explanation is lengthy), every sentence adds value. It could be slightly more concise, but it is appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 parameters, no output schema, no annotations), the description is highly complete. It explains all parameters, specifies return type ('The analysis result as text'), and provides comprehensive examples covering various use cases. The default system prompt is also elaborated, which adds valuable context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate entirely. It does so excellently by providing detailed explanations for all 10 parameters, including their purpose, defaults, and constraints. For example, it explains that 'query' should include context for better results and provides examples. This enables correct parameter usage without relying on the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Analyze an image using OpenRouter's vision capabilities.' It specifies the action (analyze), resource (image), and technology (OpenRouter's vision), leaving no ambiguity. With no sibling tools, differentiation is not needed, but the purpose is specific and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage guidance through detailed parameter descriptions and multiple examples covering file paths, URLs, contextual queries, and custom system prompts. However, it does not explicitly state when not to use this tool or mention alternatives, though none exist. 'Clear context, no exclusions' accurately reflects this.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion between tools. The tool's purpose is clear and unique.

Naming Consistency5/5

A single tool means no inconsistency in naming patterns. The name 'image_analysis' is descriptive and follows a common noun_noun convention.

Tool Count3/5

A single tool for a vision server feels slightly thin. While the one tool is comprehensive, the server scope seems narrow; typically 3-15 tools are expected for a well-scoped server.

Completeness2/5

The server only offers image analysis. Missing other common vision operations like model listing, batch processing, or generation. The surface is incomplete for a vision-focused server.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Nazruden/mcp-openvision'

If you have feedback or need assistance with the MCP directory API, please join our Discord server