MCP OpenVision

Überblick

MCP OpenVision ist ein Model Context Protocol (MCP)-Server, der Bildanalysefunktionen auf Basis von OpenRouter-Vision-Modellen bereitstellt. Er ermöglicht KI-Assistenten die Bildanalyse über eine einfache Schnittstelle innerhalb des MCP-Ökosystems.

Related MCP server: MCP Read Images

Installation

Installation über Smithery

So installieren Sie mcp-openvision für Claude Desktop automatisch über Smithery :

npx -y @smithery/cli install @Nazruden/mcp-openvision --client claude

Verwenden von pip

pip install mcp-openvision

Verwendung von UV (empfohlen)

uv pip install mcp-openvision

Konfiguration

MCP OpenVision erfordert einen OpenRouter-API-Schlüssel und kann über Umgebungsvariablen konfiguriert werden:

• OPENROUTER_API_KEY (erforderlich): Ihr OpenRouter-API-Schlüssel

• OPENROUTER_DEFAULT_MODEL (optional): Das zu verwendende Vision-Modell

OpenRouter Vision-Modelle

MCP OpenVision funktioniert mit jedem OpenRouter-Modell, das Vision-Funktionen unterstützt. Das Standardmodell ist qwen/qwen2.5-vl-32b-instruct:free , Sie können jedoch jedes andere kompatible Modell angeben.

Zu den über OpenRouter verfügbaren beliebten Vision-Modellen gehören:

• qwen/qwen2.5-vl-32b-instruct:free (Standard)

• anthropic/claude-3-5-sonnet

• anthropic/claude-3-opus

• anthropic/claude-3-sonnet

• openai/gpt-4o

Sie können benutzerdefinierte Modelle angeben, indem Sie die Umgebungsvariable OPENROUTER_DEFAULT_MODEL festlegen oder den model direkt an die Funktion image_analysis übergeben.

Verwendung

Testen mit MCP Inspector

Am einfachsten testen Sie MCP OpenVision mit dem MCP Inspector-Tool:

npx @modelcontextprotocol/inspector uvx mcp-openvision

Integration mit Claude Desktop oder Cursor

1. Bearbeiten Sie Ihre MCP-Konfigurationsdatei:

   • Windows: %USERPROFILE%\.cursor\mcp.json

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

2. Fügen Sie die folgende Konfiguration hinzu:

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

Lokale Ausführung für die Entwicklung

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

# Run the server module directly
python -m mcp_openvision

Merkmale

MCP OpenVision bietet das folgende Kerntool:

• image_analysis : Analysieren Sie Bilder mit Bildmodellen und unterstützen Sie verschiedene Parameter:

  • image : Kann bereitgestellt werden als:

    • Base64-kodierte Bilddaten

    • Bild-URL (http/https)

    • Lokaler Dateipfad

  • query : Benutzeranleitung für die Bildanalyseaufgabe

  • system_prompt : Anweisungen, die die Rolle und das Verhalten des Modells definieren (optional)

  • model : Zu verwendendes Vision-Modell

  • temperature : Steuert die Zufälligkeit (0,0–1,0)

  • max_tokens : Maximale Antwortlänge

Erstellen effektiver Abfragen

Der query ist entscheidend für aussagekräftige Ergebnisse der Bildanalyse. Eine gut formulierte Abfrage liefert Kontext zu:

1. Zweck : Warum Sie dieses Bild analysieren

2. Schwerpunktbereiche : Bestimmte Elemente oder Details, auf die Sie achten sollten

3. Erforderliche Informationen : Die Art der Informationen, die Sie extrahieren müssen

4. Formateinstellungen : Wie die Ergebnisse strukturiert sein sollen

Beispiele für effektive Abfragen

Indem Sie den Kontext dazu angeben, warum Sie die Analyse benötigen und welche spezifischen Informationen Sie suchen, helfen Sie dem Modell, sich auf relevante Details zu konzentrieren und wertvollere Erkenntnisse zu gewinnen.

Beispielverwendung

# 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."
)

Bildeingabetypen

Das Tool image_analysis akzeptiert verschiedene Arten von Bildeingaben:

1. Base64-codierte Zeichenfolgen

2. Bild-URLs – müssen mit http:// oder https:// beginnen

3. Dateipfade :

   • Absolute Pfade : vollständige Pfade, die mit / (Unix) oder Laufwerksbuchstaben (Windows) beginnen

   • Relative Pfade : Pfade relativ zum aktuellen Arbeitsverzeichnis

   • Relative Pfade mit project_root : Verwenden Sie den Parameter project_root , um ein Basisverzeichnis anzugeben

Verwenden relativer Pfade

Wenn Sie relative Dateipfade verwenden (wie „examples/image.jpg“), haben Sie zwei Möglichkeiten:

1. Der Pfad muss relativ zum aktuellen Arbeitsverzeichnis sein, in dem der Server ausgeführt wird

2. Oder Sie können einen project_root -Parameter angeben:

# 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?"
)

Dies ist insbesondere bei Anwendungen nützlich, bei denen das aktuelle Arbeitsverzeichnis möglicherweise nicht vorhersehbar ist oder wenn Sie auf Dateien mithilfe von Pfaden relativ zu einem bestimmten Verzeichnis verweisen möchten.

Entwicklung

Einrichten der Entwicklungsumgebung

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

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

Codeformatierung

Dieses Projekt verwendet Black zur automatischen Codeformatierung. Die Formatierung wird durch GitHub Actions erzwungen:

• Der gesamte Code, der in das Repository übertragen wird, wird automatisch mit Black formatiert

• Für Pull Requests von Repository-Mitarbeitern formatiert Black den Code und committet ihn direkt in den PR-Zweig.

• Für Pull Requests von Forks erstellt Black einen neuen PR mit dem formatierten Code, der in den ursprünglichen PR integriert werden kann.

Sie können Black auch lokal ausführen, um Ihren Code vor dem Commit zu formatieren:

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

Tests ausführen

pytest

Freigabeprozess

Dieses Projekt verwendet einen automatisierten Freigabeprozess:

1. Aktualisieren Sie die Version in pyproject.toml gemäß den Prinzipien der semantischen Versionierung

   • Sie können das Hilfsskript verwenden: python scripts/bump_version.py [major|minor|patch]

2. Aktualisieren Sie die CHANGELOG.md mit Details zur neuen Version

   • Das Skript erstellt außerdem einen Vorlageneintrag in CHANGELOG.md, den Sie ausfüllen können

3. Übernehmen und übertragen Sie diese Änderungen in den main

4. Der GitHub Actions-Workflow wird:

   • Erkennen der Versionsänderung

   • Automatisch eine neue GitHub-Version erstellen

   • Lösen Sie den Veröffentlichungsworkflow aus, der auf PyPI veröffentlicht

Diese Automatisierung trägt dazu bei, einen konsistenten Veröffentlichungsprozess aufrechtzuerhalten und stellt sicher, dass jede Veröffentlichung ordnungsgemäß versioniert und dokumentiert ist.

Unterstützung

Wenn Sie dieses Projekt hilfreich finden, denken Sie darüber nach, mir einen Kaffee zu spendieren, um die laufende Entwicklung und Wartung zu unterstützen.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .