Instagram Analytics MCP

Un servidor MCP que responde preguntas sobre el rendimiento de los reels de Instagram en lenguaje natural, en múltiples cuentas.

No se trata de que envuelva una API. Es que el número que realmente predice el alcance no existe en la API de Instagram, así que el servidor lo calcula.

"How did my last 10 reels do?"
"What worked best this month?"
"Which of my accounts is working?"

El problema que resuelve

La API Graph de Instagram devuelve vistas, alcance, guardados, compartidos y tiempo medio de visualización.

No devuelve la tasa de finalización -- la proporción del vídeo que la gente realmente ve. En una cuenta real medida a lo largo de ~700 reels, la finalización es lo que separa un reel que muere de uno que se difunde:

Las vistas son el resultado. La finalización es la causa, y se puede leer a las pocas horas de publicar, no a los días.

Calcularla necesita avg_watch_time / duration. La duración tampoco está en la API. Así que el servidor sondea la media_url de cada vídeo con ffprobe para medirla.

Esa es toda la razón de que esto exista. Dos saltos que la API no hará por ti, más una valoración de umbral sobre la que la API no tiene opinión.

Herramientas

Cada reel vuelve con fecha, finalización, una etiqueta verdict, duración, vistas, alcance, guardados, compartidos, la primera línea del pie de foto como gancho y un permalink.

Funciona con una cuenta o con varias. account es opcional y por defecto usa la primera que configures.

Requisitos

• Una cuenta Profesional de Instagram (Empresa o Creador). Las cuentas personales no pueden usar la API de Instagram en absoluto

• Python 3.10+

• ffprobe (brew install ffmpeg) -- sin él no hay duración, así que no hay tasa de finalización

Configuración

git clone https://github.com/sskghub/instagram-analytics-mcp
cd instagram-analytics-mcp

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

cp .env.example .env

Luego obtén un token. SETUP.md es la guía completa, unos 15 minutos para la primera cuenta: crea una app de Meta, añade Instagram, genera un token.

Una vez que hay un token en .env, esto comprueba todo y te dice el id de cuenta para que lo pegues de nuevo, de modo que nunca tengas que buscarlo:

.venv/bin/python check_setup.py

[  OK  ] mcp package installed
[  OK  ] ffprobe found
[  OK  ] main: token works, account @yourhandle

Luego confirma que extrae datos reales y que la capa MCP funciona de extremo a extremo:

.venv/bin/python server.py --selftest
.venv/bin/python test_server.py

Regístralo en Claude Code:

claude mcp add ig-analytics -- /absolute/path/.venv/bin/python /absolute/path/server.py

El servidor lee su propio .env, así que no hay credenciales en el archivo de configuración de MCP. Esa configuración se guarda en el repositorio; los tokens no.

Añadir otra cuenta significa añadir dos líneas a .env. No hay código que editar: las cuentas se descubren a partir de los nombres de las variables.

Caducidad del token

Los tokens de Instagram duran ~60 días. Cuando uno caduca, todo lo que depende de él devuelve silenciosamente nada.

refresh_tokens.py intercambia un token aún válido por uno nuevo de 60 días:

python refresh_tokens.py --if-older-than 7

Ejecútalo semanalmente. La restricción que da forma al diseño: un token caducado no se puede renovar. Meta no renovará un token muerto, así que renovar pronto es la única estrategia que funciona. Cada renovación restablece los 60 días completos, así que las renovaciones tempranas no cuestan nada.

Las notas sobre la programación, incluida la trampa de macOS en la que un trabajo de launchd no puede leer tus archivos en silencio, están en SETUP.md.

Hace una copia de seguridad de .env antes de escribir, reescribe las claves duplicadas y avisa en caso de fallo.

Renovar no invalida el token antiguo, así que varias máquinas pueden renovar cada una su propio .env de forma independiente. Los valores de los tokens nunca necesitan sincronizarse entre hosts.

Notas de su construcción

Cosas que costaron tiempo real, mantenidas aquí porque son las partes que se generalizan.

sys.exit() está bien en una CLI y es fatal en un servidor. La primera versión reutilizaba una función de un script de línea de comandos existente. Esa función llamaba a sys.exit() cuando un token era rechazado, lo que habría matado todo el proceso del servidor el día que un token caducara. Las herramientas ahora lanzan ValueError; el SDK convierte las excepciones estándar en resultados legibles sobre los que el modelo puede actuar, y el servidor sobrevive.

Los errores deben decir qué hacer. Un token muerto devuelve los pasos para regenerarlo, no un stack trace. El modelo puede transmitírselo a un humano que pueda arreglarlo de verdad.

El docstring es la interfaz. Así es como el modelo decide si llamar a una herramienta o no, así que cada una dice cuándo recurrir a ella, no solo qué devuelve.

Los trabajos programados pueden fallar en silencio. En macOS, un temporizador de launchd para el script de renovación falló con Operation not permitted, porque TCC bloquea a los agentes en segundo plano la lectura de directorios protegidos. Aparecía como cargado y habría permanecido sin ejecutarse silenciosamente. Forzar una ejecución y leer el registro es la única forma de que salga a la luz.

Las claves duplicadas en .env son una trampa real. Un duplicado obsoleto puede eclipsar un token recién escrito dependiendo de cómo los resuelva el cargador, así que el escritor reescribe cada aparición en lugar de la primera.

La API cambió de nombres. Es mcp.server.mcpserver.MCPServer; la ruta anterior mcp.server.fastmcp.FastMCP se eliminó en mcp 2.x, junto con otros módulos heredados. La mayoría de los ejemplos en línea todavía muestran la importación antigua y no funcionarán.

Licencia

MIT