visionMCP 👁️

Die Augen eines größeren Reasoning-LLMs.

visionMCP ist ein Model Context Protocol-Server, der jedem MCP-fähigen Agenten echtes Sehen ermöglicht. Ein reines Text-Reasoning-Modell kann alles, was es nicht sehen kann, an diesen Server delegieren: einen Screenshot beschreiben, eine Frage zu einem Foto beantworten, ein Dokument per OCR erfassen oder zwei Bilder vergleichen – der Server übernimmt das Sehen und gibt Text zurück.

Es funktioniert mit allen drei großen Vision-Backends, die zur Laufzeit aus einer einzigen config.json ausgewählt werden:

Funktionen

• 🔍 Vier Vision-Tools für ein Reasoning-LLM zum Aufrufen:

  • describe_image — vollständige Beschreibung in natürlicher Sprache

  • ask_about_image — gezielte Fragen & Antworten zu jedem Bild

  • extract_text — OCR / Transkription

  • compare_images — Seitenweise-Vergleich

• 🖼️ Jede Quelle wird akzeptiert: lokale Dateipfade, http(s)-URLs und base64 data:-URIs.

• 📦 Keine Bildvorbereitung: überdimensionierte Bilder werden automatisch verkleinert und als JPEG neu kodiert, um die Payload-Limits des Anbieters einzuhalten.

• 🔌 Drei Transporte: stdio (Standard, für lokale MCP-Clients), http (Streamable HTTP für Remote-Hosting) oder sse (Legacy Server-Sent Events).

• ⚙️ Eine config.json steuert Anbieter, API-Schlüssel, API-URL und Modell. Umgebungsvariablen und CLI-Flags können alles überschreiben.

• 🚀 uv-verwaltet, installierbar, ausführbar und hostbar.

Related MCP server: depu-img-mcp

Schnellstart

1. Installieren

Erfordert uv und Python ≥ 3.10.

cd visionMCP
uv sync

2. Konfigurieren

Die mitgelieferte config.json funktioniert bereits mit einem lokalen Ollama. Wechseln Sie den Anbieter, indem Sie die Datei bearbeiten:

// config.json
{
  "provider": "openai",                  // "ollama" | "openai" | "anthropic"
  "api_key": "sk-...",                   // or leave "" and export OPENAI_API_KEY
  "api_url": "",                         // "" = provider default
  "model": ""                            // "" = provider default
}

Siehe docs/configuration.md für alle Optionen und docs/providers.md für die Einrichtung pro Anbieter.

Sicherheit: echte API-Schlüssel nicht in Git ablegen – kopieren Sie config.json nach config.local.json (automatisch ignoriert) oder verwenden Sie Umgebungsvariablen. Der Server protokolliert Ihren Schlüssel nie.

3. Ausführen

uv run vision-mcp                        # stdio transport (default)
uv run vision-mcp --transport http --host 0.0.0.0 --port 8100   # host remotely
uv run vision-mcp --show-config          # print resolved config (key masked)

Einbinden in einen MCP-Client

opencode (opencode.json)

{
  "mcpServers": {
    "visionMCP": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/visionMCP", "vision-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "visionMCP": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/visionMCP", "vision-mcp"]
    }
  }
}

Generischer MCP-Client (stdio)

{
  "mcpServers": {
    "visionMCP": {
      "command": "/path/to/visionMCP/.venv/bin/vision-mcp",
      "args": ["--config", "/path/to/visionMCP/config.json"]
    }
  }
}

Der Server sendet niemals Bildinhalte an die Vision-API, die über den Tool-Aufruf hinausgehen. Bildbytes werden im Speicher gehalten und nie auf die Festplatte geschrieben.

Tools-Referenz

Ein image-Argument akzeptiert jede der folgenden:

/path/to/photo.png          # local file
https://example.com/x.jpg   # URL (downloaded at call time)
data:image/png;base64,iVBORw0KGgo...   # base64 data URI

So funktioniert es

Alles läuft durch eine Funktion in src/vision_mcp/pipeline.py:

image (path / URL / data URI)  →  base64 + mime  →  vision model  →  text
        _read()                     _encode()         API[provider]    look()

Die Server-Tools sind dünne Wrapper: pipeline.look(cfg, [image], prompt).

Dokumentation

• Konfigurationsreferenz — jede Konfigurationsoption, Umgebungsvariable und Vorrangregeln

• Anbieter-Setup — Ollama, OpenAI und Anthropic, Schritt für Schritt

• Bereitstellung — Hosting über HTTP/SSE, Docker, Härtung

Entwicklung

uv sync --group dev
uv run ruff check .
uv run pytest

Lizenz

MIT