# ojos-mcp: los "ojos" de Claude para vídeo

Claude no ve un vídeo en movimiento. Este servidor MCP se lo permite combinando dos fuentes:

- **ffmpeg y OpenCV** (local, gratis): miden los tiempos exactos de cada corte, sacan fotogramas y,
  segundo a segundo, el movimiento de cámara, los destellos y los golpes de sonido.
- **Gemini** (el vídeo se envía a Google): ve el vídeo en movimiento y con audio, y describe ritmo,
  transiciones, animación de textos y uso de la música.

Sirve para analizar referencias, replicar su estilo y revisar tus propios montajes antes de publicarlos.

## Herramientas

| Herramienta | Coste | Qué hace |
|---|---|---|
| `detectar_cortes` | gratis | Lista los planos con su inicio, fin y duración exactos. |
| `extraer_fotogramas` | gratis | Guarda un JPG del centro de cada plano para que Claude lo mire. |
| `mirar_video` | Gemini | Responde a cualquier pregunta sobre un vídeo, o sobre un tramo. |
| `desmontar_referencia` | Gemini | Ficha completa de una referencia: los cortes de ffmpeg más la descripción de Gemini de cada plano. |
| `comparar_videos` | Gemini | Compara la referencia con tu resultado y propone correcciones concretas. |
| `ficha_segundo_a_segundo` | gratis + Gemini opcional | Medidas locales cada medio segundo (cámara, destellos, voz, golpes de efecto) y, si quieres, la lectura de Gemini tramo a tramo. |

Después de cada respuesta, el servidor borra de Google los vídeos que ha subido.

## Instalación (macOS)

```bash
# 1. ffmpeg
brew install ffmpeg

# 2. Código y entorno de Python
git clone <URL_DE_ESTE_REPO> ~/ojos-mcp
cd ~/ojos-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt -r requirements-medidas.txt

# 3. Registrarlo en Claude Code. Sustituye TU_CLAVE por tu clave de Gemini
#    (créala en https://aistudio.google.com/apikey). Se guarda en tu configuración
#    de Claude Code, nunca en este repo.
claude mcp add --scope user ojos \
  -e GEMINI_API_KEY=TU_CLAVE \
  -e OJOS_PYTHON=$HOME/ojos-mcp/venv/bin/python \
  -- ~/ojos-mcp/venv/bin/python ~/ojos-mcp/servidor.py

# 4. Comprobar
claude mcp list
```

Sin clave de Gemini también funciona: las herramientas gratis van igual y las de Gemini avisan de que falta.

## Ajustes (variables de entorno, con `-e` al registrarlo)

- `OJOS_MODELO`: modelo principal de Gemini. Por defecto, `gemini-3.8-flash`.
- `OJOS_MODELOS_RESERVA`: modelos a los que pasa solo si el principal se queda sin cuota del día
  (error 429). Por defecto, `gemini-3.6-flash,gemini-3.5-flash-lite`. El modelo agotado se salta
  durante 6 horas, y la respuesta indica qué modelo contestó.
- `OJOS_DURACION_MAX_S`: duración máxima de vídeo que se envía a Gemini. Por defecto, 300 s, para
  no gastar sin querer. Los vídeos más largos se analizan por tramos.
- `OJOS_LIMITE_LLAMADA_S`: tiempo máximo de espera por llamada a Gemini. Por defecto, 240 s.
- `OJOS_PYTHON`: el Python con numpy y OpenCV que usa `ficha_segundo_a_segundo`.

## Coste y privacidad

- Cada segundo de vídeo cuesta unos 300 tokens por fotograma analizado más el audio. Las herramientas
  usan 2–8 fotogramas por segundo para no perder cortes rápidos: más fps, más coste.
- Con la cuota gratuita de Gemini, Google puede usar lo que le envías para mejorar sus productos. No
  subas vídeos con datos personales de terceros sin su permiso.
- Lo que dice Gemini es una opinión y puede equivocarse. Los tiempos de ffmpeg son medidas: si no
  coinciden, mandan los de ffmpeg.

## Ejemplo de uso con Claude

> Con ojos: desmonta ~/Movies/referencia.mp4 y dime cómo está montada, plano a plano.

> Compara ~/Movies/referencia.mp4 con ~/Movies/mi_version.mp4 y dame los 3 cambios que más acercan
> mi versión a la referencia.