ollama-vision-mcp

Englisch · 中文

Ein minimaler Brückendienst, der lokale Bildverarbeitungsfunktionen für VS Code Copilot mit reinen Textmodellen (z. B. DeepSeek) bereitstellt.

Wenn Copilot ein reines Textmodell verwendet, kann es Bilder nicht direkt „sehen“. Dieser MCP-Server schließt diese Lücke: Sie legen einen Screenshot in einen Ordner; Copilot liest das Bild über diese Brücke → sendet es an ein lokales Ollama-Vision-Modell → erhält eine Textbeschreibung zurück, die das reine Textmodell verstehen kann.

VS Code Copilot Chat (Agent mode, text-only model)
        │  MCP stdio
        ▼
ollama-vision-mcp (this package)
        │  Read local image → base64 → POST /v1/chat/completions
        ▼
Ollama (local vision model, e.g., qwen2.5vl:7b)

Tools

Related MCP server: Hybrid Vision MCP Server

Umfang dieses Tools

Dieses Paket ist nur eine Brückenschicht. Es kommuniziert mit Ollama ausschließlich über HTTP (OpenAI-kompatible /v1/chat/completions und /v1/models).

Es übernimmt nicht:

• Installation von Ollama, Start von ollama serve, Herunterladen von Modellen oder Verwaltung der Modellkonfiguration;

• Zugriff auf die Zwischenablage, interne IDE-Mechanismen oder andere Netzwerkdienste als Ihr lokales Ollama.

Sie sind vollständig für die Installation von Ollama und das Herunterladen von Modellen verantwortlich (siehe Voraussetzungen).

Voraussetzungen

Sie müssen Folgendes selbst einrichten:

• Python 3.10+

• Ollama installiert und ausgeführt: ollama serve

• Mindestens ein Vision-Modell heruntergeladen; empfohlen:

  bash

  ollama pull qwen2.5vl:7b

  Weitere Optionen: qwen3-vl:8b, gemma3:12b, llama3.2-vision:11b, llava:7b. Wählen Sie ein für Ihre GPU geeignetes Modell; geben Sie es später über die Umgebungsvariable VISION_MCP_MODEL an.

🚀 Schnellinstallation (Empfohlen)

Führen Sie einen einzigen Befehl im Repository-Stammverzeichnis aus, um Installation und Konfiguration abzuschließen:

bash

cd ollama-vision-mcp
python setup_mcp.py

Das Skript wird automatisch:

1. Eine dedizierte virtuelle Umgebung (.venv) erstellen und dieses Paket installieren (ohne die globale Umgebung zu beeinträchtigen).

2. Den lokalen Ollama-Dienst erkennen und die verfügbaren Vision-Modelle auflisten.

3. Sie interaktiv durch die Einstellung von base_url, model, inbox, max_tokens, Bildkomprimierung und einem optionalen API-Schlüssel führen.

4. Die Konfiguration in die Projektdatei .vscode/mcp.json und/oder die benutzerweite globale MCP-Datei (%APPDATA%\Code\User\mcp.json) schreiben, zusammengeführt mit vorhandenen Einstellungen, ohne Ihre anderen MCP-Server zu überschreiben.

Nicht-interaktive Nutzung (geeignet für CI/Skripte):

bash

python setup_mcp.py --yes --project --model qwen2.5vl:7b
python setup_mcp.py --print         # Only prints the config JSON, does not write to file

Nach der Installation laden Sie das Fenster in VS Code neu (Strg+Umschalt+P → „Developer: Reload Window“), damit die Konfiguration wirksam wird.

Wenn Sie es bereits ausgeführt haben, können Sie es auch einfach mit dem Befehl ollama-vision-setup neu konfigurieren.

Installation überprüfen

Geben Sie in VS Code Copilot Chat (Agent-Modus) ein:

text

Run vision_status

Wenn das zurückgegebene JSON "ollama": { "ok": true, ... } und die Modellliste enthält, ist die Verbindung erfolgreich. Wenn ok falsch ist, starten Sie zuerst Ollama (ollama serve) und versuchen Sie es erneut.

Verwendung

1. Legen Sie Screenshots in das Inbox-Verzeichnis des Projekts (Standard: .ai/inbox). Der Server erstellt dieses Verzeichnis bei Bedarf automatisch.

2. Stellen Sie eine Frage in Copilot Chat, zum Beispiel:

   „Schauen Sie sich die Screenshots im Posteingang an und sagen Sie mir, worum es bei diesem Fehler geht.“

3. Der Agent ruft automatisch list_images → describe_image auf und antwortet basierend auf der Textbeschreibung.

Den Agenten intelligenter machen (optional): Kopieren Sie die vorgefertigte Anweisungsdatei .github/instructions/ollama-vision/vision-tools.instructions.md in denselben Pfad in Ihrem Projekt. Sie vermittelt dem Agenten den vollständigen Vision-Workflow – Aufrufreihenfolge (list_images → describe_image → extract_text), Modusauswahl, Fehlerbehebung und Anleitung, Screenshots in den Posteingang zu legen. Als VS-Code-Dateianweisung wird sie bei Bedarf immer dann erkannt, wenn die Aufgabe Bilder betrifft, und funktioniert daher ohne Einrichtung sofort.

Referenz der Umgebungsvariablen

Kompatibilitäts-Aliasse: VISION_MODEL, VISION_BASE_URL, VISION_INBOX, VISION_API_KEY

Manuelle Installation (Alternative)

Wenn Sie die volle manuelle Kontrolle über jeden Schritt benötigen, beachten Sie den folgenden Ablauf.

1. Umgebung erstellen und installieren

bash

cd ollama-vision-mcp
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate    # macOS / Linux
pip install -e .

Nach der Installation erhalten Sie zwei Befehle:

• ollama-vision-mcp — startet den MCP-Server

• ollama-vision-setup — interaktive Konfigurationsabkürzung

2. Bei VS Code registrieren

Kopieren Sie Folgendes in die .vscode/mcp.json Ihres Projekts (nur Projekt) oder in die benutzerweite Datei %APPDATA%\Code\User\mcp.json (alle Projekte). Stellen Sie sicher, dass Sie command auf den absoluten Pfad des Python-Interpreters Ihrer virtuellen Umgebung ändern:

json

{
  "servers": {
    "ollama-vision": {
      "type": "stdio",
      "command": "D:/MyRepos/ollama-vision-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "ollama_vision_mcp"],
      "env": {
        "VISION_MCP_BASE_URL": "http://localhost:11434/v1",
        "VISION_MCP_MODEL": "qwen2.5vl:7b",
        "VISION_MCP_INBOX": ".ai/inbox"
      }
    }
  }
}

⚠️ command muss der absolute Pfad zum Python-Interpreter innerhalb der virtuellen Umgebung sein. Sie können auch ollama-vision-setup --project ausführen, um diese Datei automatisch zu generieren. Der Server verwendet beim Aufruf os.getcwd(), daher werden relative Pfade (wie path und das Inbox-Verzeichnis) relativ zum Projektstamm aufgelöst, in dem der Server gestartet wird.

Rauchtest

Führen Sie das folgende Skript aus, um die Ollama-Konnektivität zu überprüfen, den Inhalt des Posteingangs aufzulisten und einen echten Vision-Aufruf für das erste Bild durchzuführen:

bash

python examples/smoke_test.py

Lizenz

MIT