eyes-mcp

Dale ojos a cualquier LLM de solo texto. Visión local para tu agente de codificación.

Un comando · cero API keys · nada sale de tu máquina

DeepSeek, GLM, Qwen-Coder, Llama… grandes modelos, todos ciegos.

❌ Sin ojos

Pegas una captura de pantalla en tu agente (que ejecuta un modelo solo de texto mediante 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.

✅ Con ojos

El agente llama a un VLM local + OCR en su lugar, y lee la captura de pantalla por sí mismo:

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

Inicio rápido

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

Eso es todo. El instalador:

1. pregunta qué modelo quieres, con una recomendación calculada según tu RAM y tu GPU (omite la pregunta con EYES_PRESET o --yes),

2. instala las dependencias y descarga el modelo (~0.3 a 3.5GB, reanudable),

3. detecta cuáles de tus agentes ejecutan modelos solo de texto, leyendo tus configuraciones de Claude Code / Codex / Cursor y verificando cada modelo contra una base de datos de modalidades,

4. registra eyes-mcp solo donde se necesita. Los agentes multimodales se omiten automáticamente.

# 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

¿Solo quieres la comprobación de modalidad? python3 scripts/detect_modality.py

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

Registro manual

¿Omitiste la instalación automática, o tienes un agente que el instalador no conoce? Añádelo manualmente.

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): misma forma que Claude Code.

Reinicia el agente y luego pregunta: "¿qué hay en esta captura de pantalla?"

Herramientas

Modelos predefinidos

Extras ocultos (sigue siendo un solo comando): smol500 (SmolVLM2-500M), paddle (PaddleOCR-VL-1.6), qwen3-2b (Qwen3-VL-2B).

Cualquier otro GGUF también funciona. Apunta la variable de entorno a él y omite los preajustes por completo:

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

Buenos candidatos que no vienen como preajustes: LFM2.5-VL-1.6B/3B, InternVL3.5-2B/4B, MiniCPM-V-4.6, DeepSeek-OCR, dots.ocr, gemma-3n-E2B, moondream2. Todo lo que llama.cpp admita con un archivo mmproj funciona.

Cambia cuando quieras: configura EYES_PRESET y vuelve a ejecutar ./scripts/download_models.sh. ¿No sabes cuál? python3 scripts/choose_model.py muestra tu RAM/GPU y marca una recomendación.

Cómo funciona

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"

• El ciclo de vida sigue a tu agente: el servidor VLM se inicia cuando arranca el MCP y se apaga cuando tu agente sale, para que nunca termines con procesos huérfanos o un demonio que cuidar.

• Puerto flotante: el VLM nunca se vincula a un puerto fijo (adiós, "8080 ya está en uso"), por lo que convive con tus otros servicios locales.

• Reutilización de VLM externo: si ya ejecutas uno en VLM_BASE_URL, eyes-mcp lo usa en lugar de lanzar el suyo propio.

Por qué

Los modelos de código más baratos y mejores actualmente (DeepSeek-V4-Flash, GLM-5.x, Qwen-Coder) son solo de texto. Cada plataforma asume que puedes pegar una captura de pantalla, y todos estos modelos fallan silenciosamente. eyes-mcp es el sidecar que faltaba: un pequeño VLM local más OCR, envuelto en el ciclo de vida que tu agente ya entiende.

Hoja de ruta

• Inicio diferido del VLM (se lanza en la primera llamada a una herramienta, no al iniciar MCP)

• screenshot_analyze (captura la pantalla, sin necesidad de archivo)

• Páginas PDF → visión

• Instalador de una línea npx eyes-mcp

• Plantillas de prompt por modelo (los modelos OCR de llama.cpp necesitan prompts específicos)

Preguntas frecuentes

¿Importa el modelo de mi agente? Solo en que debe ser solo de texto para que esto sea útil. Los modelos multimodales (GPT, Claude, GLM-V) ya ven imágenes, así que no te molestes.

¿Se necesita GPU? No. Funciona bien en CPU, y llama.cpp detecta Apple Metal o CUDA automáticamente si están presentes.

¿Dónde se almacenan los modelos? ~/.eyes-mcp/models/<preset>/. Bórralos para restablecer.

Licencia

MIT. Los pesos de los modelos conservan sus propias licencias (consulta la tabla de preajustes); se descargan en el momento de la instalación, nunca se redistribuyen aquí.