vision-mcp

Ein leichtgewichtiger MCP-Server, der reinen Textmodellen visuelle Fähigkeiten verleiht. Wenn das Hauptmodell auf Bilder stößt (Screenshots, UI-Diagramme, Flussdiagramme, Fehlerscreenshots usw.), diese aber nicht verstehen kann, werden die Bilder über MCP-Tools an ein OpenAI-kompatibles multimodales Backend (Qwen-VL, GPT-4o, Gemini, lokales vLLM usw.) zur Analyse übergeben und das Ergebnis als Text zurückgegeben.

主模型(纯文本) ──调用 MCP 工具──▶ vision-mcp ──Chat Completions──▶ 多模态模型
   Claude/Codex ◀──────文本结果───────◀──────────────────────────   Qwen-VL / GPT-4o / ...

Schnellstart

Empfohlen: Starten Sie direkt mit dem im Repository mitgelieferten bin/wrapper.sh. Beim ersten Aufruf erstellt der Wrapper automatisch ein .venv im Verzeichnis und installiert die Abhängigkeiten (bevorzugt uv, ohne uv venv+pip); eine manuelle Installation ist nicht erforderlich. Danach wird das eigentliche server.py per exec ausgeführt. Geeignet für macOS / Linux.

# 方式一（推荐，免手动装依赖）：MCP client 指向 wrapper 即可
claude mcp add vision-mcp -- /绝对/路径/vision-mcp/bin/wrapper.sh

# 或先自测：wrapper 会自举依赖并启动 server
/绝对/路径/vision-mcp/bin/wrapper.sh --check

Unter Windows verwenden Sie python -m venv + install.ps1 oder führen Sie direkt python server.py aus.

Related MCP server: vision-mcp

Installation (aus dem Quellcode)

Installieren Sie zuerst den MCP-Server selbst (Python):

# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1
# macOS / Linux
./install.sh

Dann binden Sie ihn je nach Client ein:

Claude Code

claude mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

Codex

codex mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

Nach Änderungen an der MCP-Konfiguration muss der Client neu gestartet werden, damit sie wirksam werden.

pi

cp pi-extensions/vision-mcp.ts ~/.pi/agent/extensions/
# 依赖：typebox（必需，工具参数模式定义）；sharp（可选，图片缩放，未装则自动降级为不缩放）
cd ~/.pi/agent/extensions && npm i sharp typebox

Nach dem Kopieren pi neu starten oder /reload lädt automatisch, pi install ist nicht erforderlich. Die pi-Erweiterung unterstützt Fähigkeits-Gating: Wenn das Hauptmodell Bilder nativ unterstützt (input enthält image), werden die drei visuellen Tools automatisch ausgeblendet, um unnötige Delegation zu vermeiden; sie werden nur bei reinen Textmodellen angezeigt.

Konfiguration

Priorität: config.json > Prozess-Umgebungsvariablen > .env > Standardwerte. config.json ist in .gitignore aufgenommen und wird nicht eingecheckt.

cp config.example.json config.json   # 再编辑 api_key 等字段

{
  "api": "openai-completions",
  "api_key": "sk-your-dashscope-api-key",
  "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "model": "qwen-vl-plus",
  "max_tokens": 4096,
  "timeout": 120,
  "max_retries": 2,
  "retry_backoff": 2
}

pi-Erweiterung liest zusätzlich ~/.pi/vision-mcp/config.json (oder per VISION_CONFIG_PATH angegeben); die Schlüssel entsprechen den obigen.

Unterstützte Formate: PNG / JPEG / WebP / GIF (BMP ist ausgeschlossen, da es von gängigen visuellen Backends nicht unterstützt wird).

Gängige Backends: DashScope (Standard) VISION_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1; OpenAI model=gpt-4o; lokales vLLM base_url=http://localhost:8000/v1.

Konfiguration prüfen

# wrapper 方式（依赖未装则先自举）
./bin/wrapper.sh --check
# 源码自建（依赖手动安装后）
python server.py --check   # 打印生效配置，API key 脱敏

Tools

• vision_analyze — Allgemeines Bildverständnis. Parameter: prompt (optional), image/image_path/image_url/image_base64 (eines von vier).

• vision_ocr — Extrahiert Text aus Bildern zeichenweise. Parameter wie bei analyze (ohne prompt).

• vision_analyze_batch — Batch-Analyse mehrerer Bilder. Parameter: items (erforderlich, jedes Element ist eine der vier Bildquellen, optional mit prompt), prompt (optional), concurrency (Standard 3, Bereich 1-8).

Open Source

Als Quellcode Open Source, Fork / Issue / PR sind willkommen.