# Instagram Reels MCP

Un programa chico que corre **en tu propia computadora** y le permite a Claude Desktop consultar los reels de **tu** cuenta de Instagram profesional: cuántos hiciste, cuáles rindieron más, cómo evolucionó semana a semana, etc. Las preguntas se hacen en lenguaje normal ("¿cómo nos fue este mes?").

Usa la API oficial de Meta (Instagram Graph API). No hay servidor intermedio, no hay cuenta de nadie más involucrada y el código no trae ningún dato ni clave de su autor: **cada persona crea su propia app de Meta y su propio token**.

## Qué hace y qué no hace

- Lee los reels de tu cuenta y sus métricas (vistas, alcance, me gusta, comentarios, compartidos, guardados, interacciones totales, tiempo de visualización) y las guarda en una base de datos local (SQLite).
- Solo hace consultas de **lectura**. No publica, no borra, no comenta.
- Permite marcar reels como "excepcionales" (por ejemplo, una liquidación que se salió de lo normal) para excluirlos de los resúmenes.
- Guarda una "foto" diaria de seguidores y publicaciones, para que armes tu propio historial.
- **No** cubre publicaciones de feed, stories, ni datos de otras cuentas.

Herramientas que le aparecen a Claude: `estado`, `actualizar_datos`, `resumen_reels`, `listar_reels`, `serie_semanal`, `gestionar_excepcionales`, `guardar_foto_cuenta`, `historial_cuenta`, `consultar_graph_api` (lectura libre y acotada a IDs numéricos).

## Privacidad: qué queda dónde

| Dato | Dónde queda |
|---|---|
| Token de tu página (`token.json`) | Solo en tu computadora, carpeta `instagram_reels_datos` de tu usuario. Es tu llave: **no lo compartas ni lo subas a ningún lado**. |
| Reels y métricas (`datos.db`) | Solo en tu computadora. |
| Clave secreta de la app | No se guarda: se pide una vez y se usa para generar el token. |
| Lo que Claude "ve" | Cuando le preguntás algo, el resultado de la herramienta (métricas, textos de tus reels) pasa a formar parte de la conversación con Claude, como cualquier otra cosa que escribas en el chat. |

El programa no se conecta a ningún sitio salvo `graph.facebook.com`.

## Requisitos

1. Una cuenta de Instagram **profesional** (empresa o creador) vinculada a una **página de Facebook**, y que vos puedas administrar esa página.
2. Claude Desktop.
3. Python 3.10 o superior (https://www.python.org/downloads/). En Windows, marcá la opción de agregar Python al PATH al instalar.
4. Una cuenta de desarrollador en Meta (https://developers.facebook.com/).

Fuente de los requisitos de Meta: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/overview

## Instalación paso a paso

### 1. Bajar estos archivos
Descargá el ZIP del repositorio y descomprimilo en una carpeta que no sea de sincronización pública (por ejemplo `Documentos\instagram-reels-mcp`).

### 2. Instalar las librerías
En una terminal, dentro de esa carpeta:

```
py -m pip install -r requirements.txt
```
(En macOS/Linux: `python3 -m pip install -r requirements.txt`.)

### 3. Crear tu app en Meta
1. Entrá a https://developers.facebook.com/apps/ y creá una app propia.
2. En la app, agregá el acceso a la API de Instagram con inicio de sesión de Facebook (Facebook Login for Business). Las pantallas de Meta cambian seguido; si algo no coincide, guiate por la documentación oficial: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/overview
3. Anotá el **ID de la app** y la **clave secreta** (Configuración de la app > Básica). La clave secreta tratala como una contraseña.

La app puede quedar en **modo desarrollo**: con acceso estándar los permisos funcionan para las personas que tienen un rol en tu app (vos). Para que *otras* personas usen *tu* app haría falta verificación de empresa y revisión de Meta (https://developers.facebook.com/docs/graph-api/overview/access-levels). Por eso este proyecto no comparte apps: cada uno crea la suya.

### 4. Generar un token corto en el Explorador de la API
1. Abrí https://developers.facebook.com/tools/explorer/ y elegí tu app.
2. Pedí estos permisos: `instagram_basic`, `instagram_manage_insights`, `pages_read_engagement`, `pages_show_list`. Si tu página está dentro de un portfolio comercial (Business) y más adelante el paso 5 no encuentra tus páginas, agregá también `business_management` y generá el token de nuevo.
3. Tocá "Generate Access Token", aceptá y elegí tu página y tu cuenta de Instagram.
4. Copiá el token (empieza con `EAA`). **No lo pegues en ningún chat ni lo compartas.**

### 5. Convertirlo en un token que no vence
```
py configurar_token.py
```
Te pide, sin mostrarlos en pantalla: el ID de la app, la clave secreta y el token corto (pegalo **una sola vez**), y tu zona horaria (por ejemplo `America/Argentina/Buenos_Aires`; si no sabés, Enter usa UTC). El script verifica todo, elige la página que tenga Instagram vinculado y guarda `token.json`. Según la documentación de Meta, el token de página obtenido así no vence.

### 6. Conectarlo a Claude Desktop
```
py conectar_claude_desktop.py
```
Agrega el programa a la configuración de Claude Desktop sin tocar lo que ya tengas, y hace antes una copia de respaldo. Después **cerrá Claude Desktop por completo** (también desde el Administrador de tareas) y abrilo de nuevo. En Configuración > Desarrollador tiene que aparecer `instagram-reels` "En ejecución".

Si preferís hacerlo a mano, agregá esto en `claude_desktop_config.json` (ajustá las rutas):
```json
{ "mcpServers": { "instagram-reels": { "command": "C:\\ruta\\a\\python.exe", "args": ["C:\\ruta\\a\\ig_reels_mcp.py"] } } }
```

### 7. Primera carga
En un chat nuevo de Claude Desktop pedile: *"Usá actualizar_datos con traer_historia_completa para bajar todos mis reels"*. Puede tardar varias llamadas (cada una trabaja hasta unos 45 segundos y avisa si quedan pendientes). Después probá: *"Dame un resumen de mis reels de los últimos 3 meses"*.

Para mantenerlo al día, pedile de vez en cuando *"actualizá los datos"* y *"guardá la foto de la cuenta"*.

## Cosas a tener en cuenta

- Meta puede tardar hasta 48 horas en cerrar las métricas de un reel reciente; por eso se vuelven a pedir los reels de los últimos días (14 por defecto) y no más de una vez cada 6 horas.
- `media_url` no viene en reels con música con copyright (límite de Meta).
- Las unidades de las métricas de tiempo de visualización se guardan tal como las entrega Meta, sin convertir.
- La versión de la API de Meta está fija en el código (`API = ".../v26.0"` en `ig_reels_mcp.py`). Meta retira versiones viejas con el tiempo; si algún día deja de funcionar, ese es el primer lugar donde mirar. Más info: https://developers.facebook.com/docs/graph-api/changelog
- Estado de pruebas: la lógica del programa se probó con respuestas simuladas de Meta. La versión original en la que se basa funcionó con una cuenta real, pero esta versión genérica todavía no fue probada por otras personas con cuentas reales: si algo falla, abrí un "issue" contando el mensaje de error (**sin pegar tokens**).

## Si se te filtra un token

Revocalo ya: en el Explorador de la API ejecutá `DELETE` sobre `me/permissions`, o quitá la app desde la configuración de Instagram/Facebook, y volvé a generar uno (pasos 4 y 5). Si se filtró la clave secreta, restablecela en Configuración de la app > Básica.

## Cómo está armado

- `ig_reels_mcp.py`: el servidor MCP (protocolo estándar, comunicación por stdio).
- `configurar_token.py`: se usa una vez para generar `token.json`.
- `conectar_claude_desktop.py`: registra el servidor en Claude Desktop.
- Los datos se guardan fuera del código, en `~/instagram_reels_datos` (se puede cambiar con la variable de entorno `IG_REELS_DIR`).