eyes-mcp

Gib jedem textbasierten LLM Augen. Lokale Bilderkennung für deinen Coding-Agenten.

Ein Befehl · keine API-Schlüssel · nichts verlässt deinen Rechner

DeepSeek, GLM, Qwen-Coder, Llama… großartige Modelle, alle blind.

❌ Ohne Augen

Du fügst einen Screenshot in deinen Agenten ein (der ein textbasiertes Modell über Claude Code / Codex / Cursor ausführt):

> Here's the error in my UI, fix it  [screenshot.png]

I'm sorry — I cannot see images. Please describe the error in text.

✅ Mit Augen

Der Agent ruft stattdessen ein lokales VLM + OCR auf und liest den Screenshot selbst:

> Here's the error in my UI, fix it  [screenshot.png]

I see a React hydration error in `CartDrawer.tsx:142`. The OCR shows:
"Hydration failed because the server rendered HTML didn't match the client." …

Schnellstart

git clone https://github.com/JamesbbBriz/eyes-mcp
cd eyes-mcp && ./scripts/install.sh

Das war's. Der Installer:

1. fragt, welches Modell du möchtest, mit einer Empfehlung, die aus deinem RAM und deiner GPU berechnet wird (überspringe die Frage mit EYES_PRESET oder --yes),

2. installiert Abhängigkeiten und lädt das Modell herunter (~0.3 bis 3.5GB, fortsetzbar),

3. erkennt, welche deiner Agenten textbasierte Modelle ausführen, indem es deine Claude Code / Codex / Cursor-Konfigurationen liest und jedes Modell gegen eine Modalitätsdatenbank prüft,

4. registriert eyes-mcp nur dort, wo es benötigt wird. Multimodale Agenten werden automatisch übersprungen.

# options:
EYES_PRESET=fast ./scripts/install.sh            # Qwen3.5-0.8B, natively multimodal
HF_ENDPOINT=https://hf-mirror.com ./install.sh  # mainland-CN mirror
./install.sh --yes                              # accept all recommendations, no prompts
./install.sh --dry-run                          # preview without changing anything

Nur den Modalitätscheck? python3 scripts/detect_modality.py

Voraussetzungen: Python ≥3.11, llama.cpp (brew install llama.cpp), ~1GB RAM.

Manuelle Registrierung

Auto-Installation übersprungen oder ein Agent, den der Installer nicht kennt? Füge ihn von Hand hinzu.

Claude Code (~/.claude.json → mcpServers):

"eyes-mcp": {
  "command": "uv",
  "args": ["--directory", "/ABS/PATH/eyes-mcp", "run", "eyes-mcp"],
  "env": { "EYES_PRESET": "lfm-450m" }
}

Codex (~/.codex/config.toml):

[mcp_servers.eyes-mcp]
command = "uv"
args = ["--directory", "/ABS/PATH/eyes-mcp", "run", "eyes-mcp"]
env = { EYES_PRESET = "lfm-450m" }

Cursor (.cursor/mcp.json): gleiche Struktur wie Claude Code.

Starte den Agenten neu und frag dann: „Was ist auf diesem Screenshot?“

Werkzeuge

Modell-Presets

Versteckte Extras (weiterhin ein Befehl): smol500 (SmolVLM2-500M), paddle (PaddleOCR-VL-1.6), qwen3-2b (Qwen3-VL-2B).

Jedes andere GGUF funktioniert auch. Setze die Umgebungsvariable darauf und überspringe Presets komplett:

EYES_MODEL_DIR=~/models/my-vlm  VLM_MODEL_FILE=model-Q4.gguf  VLM_MMPROJ_FILE=mmproj.gguf

Gute Kandidaten, die nicht als Presets enthalten sind: LFM2.5-VL-1.6B/3B, InternVL3.5-2B/4B, MiniCPM-V-4.6, DeepSeek-OCR, dots.ocr, gemma-3n-E2B, moondream2. Alles, was llama.cpp mit einer mmproj-Datei unterstützt, funktioniert.

Jederzeit wechseln: Setze EYES_PRESET und führe ./scripts/download_models.sh erneut aus. Nicht sicher? python3 scripts/choose_model.py zeigt deinen RAM/GPU und markiert eine Empfehlung.

So funktioniert es

Claude Code / Codex / Cursor
      │ MCP stdio
      ▼
eyes-mcp  (stateless, mcp SDK 2.x)
   ├─ analyze_image → llama.cpp llama-server (local VLM)  "understand"
   └─ ocr_image     → RapidOCR (onnx, ~20MB)             "extract text"

• Lebenszyklus folgt deinem Agenten: Der VLM-Server startet, wenn das MCP startet, und beendet sich, wenn dein Agent endet. So hast du nie verwaiste Prozesse oder einen Daemon, den du betreuen musst.

• Dynamischer Port: Der VLM bindet nie einen festen Port (tschüss, „8080 bereits in Verwendung“), sodass er mit deinen anderen lokalen Diensten koexistiert.

• Wiederverwendung externer VLMs: Wenn du bereits eins unter VLM_BASE_URL betreibst, verwendet eyes-mcp es, anstatt ein eigenes zu starten.

Warum

Die günstigsten und besten Coding-Modelle derzeit (DeepSeek-V4-Flash, GLM-5.x, Qwen-Coder) sind rein textbasiert. Jede Agenten-Plattform geht davon aus, dass du einen Screenshot einfügen kannst, und jedes dieser Modelle scheitert still daran. eyes-mcp ist der fehlende Sidecar: ein kleines lokales VLM plus OCR, eingebettet in den Lebenszyklus, den dein Agent bereits versteht.

Roadmap

• Verzögerter VLM-Start (erst beim ersten Tool-Aufruf starten, nicht beim MCP-Start)

• screenshot_analyze (Bildschirm erfassen, keine Datei nötig)

• PDF-Seiten → Bilderkennung

• npx eyes-mcp Einzeiler-Installation

• Prompt-Vorlagen pro Modell (llama.cpp-OCR-Modelle benötigen spezifische Prompts)

FAQ

Spielt mein Agentenmodell eine Rolle? Nur insofern, als es rein textbasiert sein muss, damit das nützlich ist. Multimodale Modelle (GPT, Claude, GLM-V) sehen Bilder bereits, also lass es.

Wird eine GPU benötigt? Nein. Es läuft problemlos auf der CPU, und llama.cpp erkennt Apple Metal oder CUDA automatisch, wenn vorhanden.

Wo werden Modelle gespeichert? ~/.eyes-mcp/models/<preset>/. Lösche sie, um zurückzusetzen.

Lizenz

MIT. Die Modellgewichte behalten ihre eigenen Lizenzen (siehe Preset-Tabelle); sie werden bei der Installation heruntergeladen und hier nie weiterverteilt.