Vision MCP

Ermöglicht LLMs ohne visuelle Fähigkeiten (wie GLM), Bilder in Claude Code / Codex zu verarbeiten.

Funktionsweise

Wenn das Hauptmodell auf ein Bild stößt, ruft es das von diesem MCP bereitgestellte Tool describe_image auf:

1. Das Tool liest die lokale Bilddatei

2. Es ruft das von dir konfigurierte Vision-Modell auf (Qwen-VL / GPT-4o / GLM-4V / Doubao oder jede beliebige OpenAI-kompatible Schnittstelle)

3. Es gibt eine Textbeschreibung an das Hauptmodell zurück

4. Das Hauptmodell setzt seine Überlegungen auf der Grundlage des Texts fort

Das Hauptmodell kommt während des gesamten Ablaufs nicht mit den Binärdaten des Bilds in Berührung, sodass es auch von reinen Textmodellen verwendet werden kann.

Das Projekt hat keinerlei Drittanbieter-Abhängigkeiten (reine Python-Standardbibliothek), läuft ab Python 3.8+ und benötigt keine pip-Installation.

Related MCP server: Image-Vision MCP Server

Ein-Klick-Installation

git clone https://github.com/Ruiba0/Vision-MCP.git
cd vision-mcp
python3 install.py

Unter Windows gibt es keinen python3-Befehl; verwende stattdessen python install.py. Das Gleiche gilt für alle python3-Befehle weiter unten.

Das Installationsskript führt die folgenden Schritte interaktiv durch:

• Lässt dich die Base-URL / den Modellnamen / den API-Key des Vision-Modells eintragen (mit Referenzen zu gängigen Anbietern)

• Registriert das MCP bei Claude Code (claude mcp add)

• Registriert das MCP bei Codex (schreibt in ~/.codex/config.toml)

• Fügt Bildverarbeitungsregeln in ~/.claude/CLAUDE.md und ~/.codex/AGENTS.md hinzu

Das Skript ist idempotent und kann wiederholt ausgeführt werden.

Manuelle Installation

Wenn du das Installationsskript nicht verwenden möchtest:

1. Vision-Modell konfigurieren

   Kopiere config.example.json zu config.json und trage deine Vision-Modell-Konfiguration ein:

   {
     "vision_api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
     "vision_model": "qwen-vl-max",
     "vision_api_key": "sk-你的key",
     "max_image_bytes": 10485760
   }

2. Bei Claude Code registrieren

   claude mcp add --scope user vision -- python3 /绝对路径/server.py

   Füge --scope user hinzu, um es global verfügbar zu machen (ohne den Parameter gilt es nur im aktuellen Verzeichnis).

3. Bei Codex registrieren

   Bearbeite ~/.codex/config.toml und füge Folgendes hinzu:

   [mcp_servers.vision]
   command = "python3"
   args = ["/绝对路径/server.py"]

4. Bildverarbeitungsregeln hinzufügen

   Füge in ~/.claude/CLAUDE.md und ~/.codex/AGENTS.md den folgenden Inhalt hinzu (damit das Hauptmodell bei Bildern proaktiv das Tool aufruft):

   ## 图片处理
   
   当用户提到图片文件路径（.png/.jpg/.jpeg/.gif/.webp/.bmp），或要求查看/分析/识别某个图片文件时：
   
   - 先判断当前主模型自身是否具备视觉能力
   - 具备视觉（如 Claude Sonnet/Opus、GPT-4o、Qwen-VL 等多模态模型）→ 直接读取图片并分析
   - 不具备视觉（如 GLM 等纯文本模型）→ 调用 vision MCP 的 describe_image 工具，传入图片路径和问题
   - 不确定自身是否支持视觉时，默认调用 describe_image 工具作为兜底
   - 用户明确要求"用 MCP 看"或"调视觉模型"时，无论主模型是否支持视觉，都调用 describe_image 工具

Unterstützte Vision-Modelle

Jedes Vision-Modell, das mit dem OpenAI-Protokoll kompatibel ist, kann verwendet werden:

Wenn du das native Anthropic-Protokoll verwenden möchtest (z. B. Claude), musst du vision_client.py selbst anpassen; derzeit wird nur das OpenAI-kompatible Protokoll unterstützt.

Verwendung

Starte Claude Code / Codex nach der Installation neu. In der Konversation kannst du dann zum Beispiel:

• „Sieh dir das Bild unter ~/Desktop/diagram.png an"

• „Analysiere den Fehler in ~/Screenshots/error.jpg"

• „Erkenne den gesamten Text in ~/Documents/notes/page1.jpeg"

(Auf Windows sehen Pfade zum Beispiel so aus: D:/temp/diagram.png – schreibe sie passend zu deinem System.)

Das Hauptmodell ruft automatisch das Tool describe_image auf; das Tool gibt die Textbeschreibung des Vision-Modells zurück, und das Hauptmodell antwortet auf dieser Grundlage weiter.

Tool-Parameter

describe_image(path: str, question: str = "详细描述这张图片的内容") -> str

• path: absoluter Pfad zur Bilddatei; unterstützt werden png/jpg/jpeg/gif/webp/bmp

• question: die Frage, die du dem Vision-Modell stellen möchtest; je nach Szenario anpassbar („Text erkennen", „Layout beschreiben", „Diagramme analysieren" usw.)

Projektstruktur

vision-mcp/
├── server.py              # MCP 服务（内置 stdio JSON-RPC 实现，无 SDK 依赖）
├── vision_client.py       # 视觉模型调用（OpenAI 兼容协议，urllib 实现）
├── config.example.json    # 配置模板（提交到 git）
├── config.json            # 你的实际配置（gitignored）
├── install.py             # 一键安装脚本
└── README.md

FAQ

F: Beim Aufruf erscheint 视觉模型连接失败

Überprüfe, ob der Pfad von vision_api_base korrekt ist. Das Tool hängt /chat/completions an die Base-URL an; die Base-URL sollte daher keinen /chat/completions-Suffix enthalten.

F: Beim Aufruf erscheint HTTP 401

Der API-Key ist ungültig oder du hast keine Berechtigung für dieses Modell. Überprüfe, ob vision_api_key und vision_model zur jeweiligen Plattform passen.

F: Das Hauptmodell ruft das Tool nicht proaktiv auf

Stelle sicher, dass die Bildverarbeitungsregeln in CLAUDE.md / AGENTS.md hinzugefügt wurden. Die Schlüsselwörter in den Regeln (Bild, Ansehen, Analysieren) leiten das Hauptmodell dazu, describe_image aufzurufen.

F: Ich möchte das Vision-Modell wechseln

Bearbeite einfach config.json und ändere die drei Felder; der Code muss nicht angefasst werden. Oder führe python3 install.py erneut aus, um neu zu konfigurieren.

Abhängigkeiten

• Python 3.8+ (reine Standardbibliothek; es müssen keine Pakete per pip installiert werden)

Lizenz

MIT