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).

Related MCP server: Instagram MCP Server

Privacidad: qué queda dónde

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):

{ "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).