eyes-mcp

Дайте любому текстовому LLM глаза. Локальное зрение для вашего кодинг-агента.

Одна команда · ноль API-ключей · ничего не покидает вашу машину

DeepSeek, GLM, Qwen-Coder, Llama… отличные модели, но все слепые.

❌ Без глаз

Вы вставляете скриншот в своего агента (работающего на текстовой модели через Claude Code / Codex / Cursor):

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

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

✅ С глазами

Агент вместо этого обращается к локальной VLM + OCR и сам читает скриншот:

> 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." …

Быстрый старт

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

Вот и всё. Установщик:

1. спрашивает, какую модель вы хотите, с рекомендацией на основе вашей RAM и GPU (пропустите вопрос с помощью EYES_PRESET или --yes),

2. устанавливает зависимости и загружает модель (~0.3–3.5GB, с докачкой),

3. определяет, какие из ваших агентов работают на текстовых моделях, читая конфиги Claude Code / Codex / Cursor и проверяя каждую модель по базе модальностей,

4. регистрирует eyes-mcp только там, где это нужно. Мультимодальные агенты пропускаются автоматически.

# 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

Нужна только проверка модальности? python3 scripts/detect_modality.py

Требования: Python ≥3.11, llama.cpp (brew install llama.cpp), ~1GB RAM.

Ручная регистрация

Пропустили автоматическую установку или используете агента, которого установщик не знает? Добавьте его вручную.

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): та же структура, что и у Claude Code.

Перезапустите агента и спросите: "что на этом скриншоте?"

Инструменты

Пресеты моделей

Скрытые дополнения (всё ещё одна команда): smol500 (SmolVLM2-500M), paddle (PaddleOCR-VL-1.6), qwen3-2b (Qwen3-VL-2B).

Подойдёт любой другой GGUF. Укажите на него через env и полностью пропустите пресеты:

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

Хорошие кандидаты, не входящие в пресеты: LFM2.5-VL-1.6B/3B, InternVL3.5-2B/4B, MiniCPM-V-4.6, DeepSeek-OCR, dots.ocr, gemma-3n-E2B, moondream2. Подойдёт всё, что llama.cpp поддерживает с файлом mmproj.

Переключайтесь в любой момент: задайте EYES_PRESET и снова запустите ./scripts/download_models.sh. Не уверены, какую выбрать? python3 scripts/choose_model.py покажет ваши RAM/GPU и отметит рекомендацию.

Как это работает

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"

• Жизненный цикл следует за вашим агентом: VLM-сервер запускается при старте MCP и завершается при выходе агента, так что у вас не остаётся осиротевших процессов или демона, за которым нужно следить.

• Плавающий порт: VLM никогда не привязывается к фиксированному порту (прощай, "порт 8080 уже занят"), поэтому она сосуществует с вашими другими локальными сервисами.

• Переиспользование внешней VLM: если у вас уже запущена VLM на VLM_BASE_URL, eyes-mcp использует её вместо запуска собственной.

Зачем

Самые дешёвые и лучшие кодинг-модели сейчас (DeepSeek-V4-Flash, GLM-5.x, Qwen-Coder) — текстовые. Каждая платформа предполагает, что вы можете вставить скриншот, и каждая из этих моделей молча с этим проваливается. eyes-mcp — недостающий сайдкар: небольшая локальная VLM плюс OCR, обёрнутая в жизненный цикл, который ваш агент уже понимает.

Дорожная карта

• Ленивый запуск VLM (запуск при первом вызове инструмента, а не при старте MCP)

• screenshot_analyze (захват экрана без файла)

• PDF-страницы → зрение

• npx eyes-mcp — установка одной командой

• Шаблоны промптов для каждой модели (OCR-модели llama.cpp требуют конкретных промптов)

FAQ

Имеет ли значение модель моего агента?

Только в том смысле, что она должна быть текстовой, чтобы это было полезно. Мультимодальные модели (GPT, Claude, GLM-V) уже видят изображения, так что не заморачивайтесь.

Нужен GPU?

Нет. Всё отлично работает на CPU, а llama.cpp автоматически подхватывает Apple Metal или CUDA, если они есть.

Где хранятся модели?

~/.eyes-mcp/models/<preset>/. Удалите их для сброса.

Лицензия

MIT. У весов моделей свои лицензии (см. таблицу пресетов); они загружаются при установке и здесь не распространяются.