Instagram MCP Server

Un servidor del Model Context Protocol (MCP) que ofrece una integración fluida con la API Graph de Instagram, permitiendo que las aplicaciones de IA interactúen programáticamente con cuentas de Instagram Business.

Funciones

🔧 Herramientas (controladas por el modelo)

• Get Profile Info: Obtener los detalles del perfil de Instagram Business

• Get Media Posts: Obtener publicaciones recientes de una cuenta de Instagram

• Get Media Insights: Recuperar métricas de interacción de publicaciones específicas

• Publish Media: Subir y publicar imágenes/videos en Instagram

• Get Account Pages: Listar las páginas de Facebook conectadas a la cuenta

• Get Conversations: Listar conversaciones de mensajes directos (DM) de Instagram (requiere Acceso Avanzado)

• Get Conversation Messages: Leer mensajes de conversaciones específicas (requiere Acceso Avanzado)

• Send DM: Responder a mensajes directos de Instagram (requiere Acceso Avanzado)

📊 Recursos (controlados por la aplicación)

• Profile Data: Acceso a la información del perfil, incluidos recuentos de seguidores, biografía, etc.

• Media Feed: Publicaciones recientes con métricas de interacción

• Insights Data: Análisis detallado de las publicaciones y el rendimiento de la cuenta

💬 Prompts (controlados por el usuario)

• Analyze Engagement: Prompt predefinido para analizar el rendimiento de las publicaciones

• Content Strategy: Plantilla para generar recomendaciones de contenido

• Hashtag Analysis: Prompt para evaluar el rendimiento de los hashtags

Related MCP server: instagram-mcp

Requisitos previos

1. Cuenta de Instagram Business: Debe estar conectada a una página de Facebook

2. Cuenta de desarrollador de Facebook: Requerida para el acceso a la API

3. Token de acceso: Token de acceso de larga duración con los permisos adecuados

4. Python 3.10+: Para ejecutar el servidor MCP (requerido por las dependencias de MCP)

Permisos necesarios de la API de Instagram

Acceso estándar (disponible de inmediato):

• instagram_basic

• instagram_content_publish

• instagram_manage_insights

• instagram_manage_comments

• pages_show_list

• pages_read_engagement

• pages_manage_metadata

• pages_read_user_content

• business_management

Acceso Avanzado (requiere revisión de la aplicación en Meta):

• instagram_manage_messages: requerido para las funciones de mensajería directa

⚠️ Funciones de DM de Instagram: Leer y enviar mensajes directos de Instagram requiere la aprobación de Acceso Avanzado por parte de Meta. Consulta INSTAGRAM_DM_SETUP.md para el proceso de revisión de la aplicación.

🔑 Cómo obtener las credenciales de la API de Instagram

📖 Inicio rápido: Consulta AUTHENTICATION_GUIDE.md para obtener una guía de configuración de 5 minutos.

Esta sección proporciona una guía paso a paso para obtener las credenciales necesarias para el servidor Instagram MCP.

Paso 1: Configurar la cuenta de Instagram Business

1. Convierte a cuenta de Business (si aún no lo es):

   • Abre la aplicación de Instagram → Configuración → Cuenta → Cambiar a cuenta profesional

   • Elige "Business" → Selecciona una categoría → Completa la configuración

2. Conecta con una página de Facebook:

   • Ve a Configuración de Instagram → Cuenta → Cuentas vinculadas → Facebook

   • Conecta una página de Facebook existente o crea una nueva

   • Importante: la página de Facebook debe ser tuya

Paso 2: Crear la aplicación de Facebook

1. Ve a Facebook Developers:

   • Visita developers.facebook.com

   • Inicia sesión con tu cuenta de Facebook

2. Crea una nueva aplicación:

   • Haz clic en "Crear aplicación" → Elige "Business" → Haz clic en "Siguiente"

   • Completa los detalles de la aplicación:

     • Nombre de la aplicación: elige un nombre descriptivo (p. ej., "My Instagram MCP Server")

     • Correo de contacto de la aplicación: tu dirección de correo electrónico

   • Haz clic en "Crear aplicación"

3. Añade el producto Instagram Basic Display:

   • En el panel de tu aplicación, haz clic en "Añadir producto"

   • Busca "Instagram Basic Display" → Haz clic en "Configurar"

4. Configura Instagram Basic Display:

   • Ve a Instagram Basic Display → Basic Display

   • Haz clic en "Crear nueva aplicación" en la sección de aplicaciones de Instagram

   • Acepta los términos y crea la aplicación

Paso 3: Obtener las credenciales de la aplicación

1. Obtén el ID y el secreto de la aplicación:

   • En el panel de tu aplicación de Facebook, ve a Configuración → Básico

   • Copia tu ID de la aplicación y tu Secreto de la aplicación

   • Importante: mantén el Secreto de la aplicación seguro y no lo compartas públicamente

Paso 4: Configurar el acceso a la API de Instagram Business

1. Añade el producto Instagram Graph API:

   • En el panel de tu aplicación, haz clic en "Añadir producto"

   • Busca "Instagram Graph API" → Haz clic en "Configurar"

2. Configura los permisos:

   • Ve a Instagram Graph API → Permisos

   • Solicita los siguientes permisos:

     • instagram_basic

     • instagram_content_publish

     • instagram_manage_insights

     • pages_show_list

     • pages_read_engagement

Paso 5: Generar el token de acceso

Opción A: Usar Graph API Explorer (recomendado para pruebas)

1. Ve a Graph API Explorer:

   • Visita developers.facebook.com/tools/explorer

2. Configura el explorador:

   • Selecciona tu aplicación en el menú desplegable

   • Haz clic en "Generar token de acceso"

   • Selecciona los permisos requeridos cuando se te solicite

3. Obtén el token de acceso de la página:

   • En el explorador, haz una solicitud GET a: /me/accounts

   • Busca tu página de Facebook en la respuesta

   • Copia el access_token de tu página

4. Obtén el ID de la cuenta de Instagram Business:

   • Usa el token de acceso de la página para hacer una solicitud GET a: /{page-id}?fields=instagram_business_account

   • Copia el ID de la cuenta de Instagram Business de la respuesta

Opción B: Usar el flujo de Facebook Login (recomendado para producción)

1. Configura Facebook Login:

   • En el panel de tu aplicación, añade el producto "Facebook Login"

   • Configura las URI de redirección OAuth válidas

2. Implementa el flujo de OAuth:

   # Example OAuth URL
   oauth_url = f"https://www.facebook.com/v19.0/dialog/oauth?client_id={app_id}&redirect_uri={redirect_uri}&scope=pages_show_list,instagram_basic,instagram_content_publish,instagram_manage_insights"

3. Intercambia el código por un token:

   # Exchange authorization code for access token
   token_url = f"https://graph.facebook.com/v19.0/oauth/access_token?client_id={app_id}&redirect_uri={redirect_uri}&client_secret={app_secret}&code={auth_code}"

Paso 6: Obtener un token de acceso de larga duración

Los tokens de corta duración caducan en 1 hora. Convierte el token en uno de larga duración (60 días):

curl -X GET "https://graph.facebook.com/v19.0/oauth/access_token?grant_type=fb_exchange_token&client_id={app_id}&client_secret={app_secret}&fb_exchange_token={short_lived_token}"

Paso 7: Configurar las variables de entorno

Crea un archivo .env en la raíz de tu proyecto:

# Facebook App Credentials
FACEBOOK_APP_ID=your_app_id_here
FACEBOOK_APP_SECRET=your_app_secret_here

# Instagram Access Token (long-lived)
INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token_here

# Instagram Business Account ID
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id_here

# Optional: API Configuration
INSTAGRAM_API_VERSION=v19.0
RATE_LIMIT_REQUESTS_PER_HOUR=200
CACHE_ENABLED=true
LOG_LEVEL=INFO

Paso 8: Probar la configuración

Ejecuta el script de validación para probar tus credenciales:

python scripts/setup.py

O pruébalo manualmente:

import os
import requests

# Test access token
access_token = os.getenv('INSTAGRAM_ACCESS_TOKEN')
response = requests.get(f'https://graph.facebook.com/v19.0/me?access_token={access_token}')
print(response.json())

🚨 Notas de seguridad importantes

1. Nunca subas credenciales al control de versiones

2. Usa variables de entorno o una gestión segura de secretos

3. Rota los tokens de acceso con regularidad

4. Supervisa las fechas de caducidad de los tokens

5. Usa HTTPS exclusivamente en producción

6. Implementa un manejo de errores adecuado para tokens caducados

🔄 Estrategia de renovación de tokens

Los tokens de larga duración caducan a los 60 días. Implementa la renovación automática:

# Check token validity
def check_token_validity(access_token):
    url = f"https://graph.facebook.com/v19.0/me?access_token={access_token}"
    response = requests.get(url)
    return response.status_code == 200

# Refresh token before expiration
def refresh_long_lived_token(access_token, app_id, app_secret):
    url = f"https://graph.facebook.com/v19.0/oauth/access_token"
    params = {
        'grant_type': 'fb_exchange_token',
        'client_id': app_id,
        'client_secret': app_secret,
        'fb_exchange_token': access_token
    }
    response = requests.get(url, params=params)
    return response.json().get('access_token')

📋 Solución de problemas comunes

Error: "Invalid OAuth access token"

• Comprueba si el token ha caducado

• Verifica que el token tenga los permisos necesarios

• Asegúrate de que la cuenta de Instagram esté conectada a una página de Facebook

Error: "Instagram account not found"

• Verifica que el ID de la cuenta de Instagram Business sea correcto

• Comprueba si la cuenta de Instagram está correctamente vinculada a la página de Facebook

• Asegúrate de que la cuenta sea de tipo Business, no Personal

Error: "Insufficient permissions"

• Revisa los permisos necesarios en la aplicación de Facebook

• Vuelve a generar el token de acceso con los ámbitos (scopes) correctos

• Comprueba si la aplicación está en modo Desarrollo o en modo En vivo

Problemas de límite de tasa

• Implementa retroceso exponencial (exponential backoff)

• Almacena en caché las respuestas cuando sea posible

• Supervisa las cabeceras de límite de tasa en las respuestas de la API

Instalación

1. Clona el repositorio:

git clone <repository-url>
cd ig-mcp

2. Instala las dependencias:

pip install -r requirements.txt

3. Configura las variables de entorno:

cp .env.example .env
# Edit .env with your Instagram API credentials

4. Configura el servidor MCP:

# Edit config.json with your specific settings

Configuración

Variables de entorno (.env)

INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token
FACEBOOK_APP_ID=your_facebook_app_id
FACEBOOK_APP_SECRET=your_facebook_app_secret
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id

Configuración del cliente MCP

Añade esto a la configuración de tu cliente MCP (p. ej., Claude Desktop):

{
  "mcpServers": {
    "instagram": {
      "command": "python",
      "args": ["/path/to/ig-mcp/src/instagram_mcp_server.py"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Ejemplos de uso

Uso con Claude Desktop

1. Obtener información del perfil:

Can you get my Instagram profile information?

2. Analizar publicaciones recientes:

Show me my last 5 Instagram posts and their engagement metrics

3. Publicar contenido:

Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"

Uso con el cliente MCP de Python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to the Instagram MCP server
server_params = StdioServerParameters(
    command="python",
    args=["src/instagram_mcp_server.py"]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # Get profile information
        result = await session.call_tool("get_profile_info", {})
        print(result)

Endpoints de la API cubiertos

Gestión de perfil

• Obtener información del perfil de negocio

• Actualizar los detalles del perfil (próximamente)

Gestión de medios

• Obtener publicaciones recientes

• Obtener detalles de medios específicos

• Subir y publicar contenido nuevo

• Eliminar medios (próximamente)

Analíticas e insights

• Métricas de interacción de las publicaciones (me gusta, comentarios, veces compartido)

• Insights de la cuenta (alcance, impresiones)

• Análisis del rendimiento de los hashtags

Gestión de la cuenta

• Listar las páginas de Facebook conectadas

• Cambiar entre cuentas de negocio

Límites de tasa y mejores prácticas

El servidor implementa una limitación de tasa inteligente para cumplir con los límites de la API de Instagram:

• Solicitudes de perfil: 200 llamadas por hora

• Solicitudes de medios: 200 llamadas por hora

• Publicación: 25 publicaciones al día

• Insights: 200 llamadas por hora

Mejores prácticas

1. Almacena en caché los datos a los que se accede con frecuencia

2. Usa solicitudes por lotes cuando sea posible

3. Implementa retroceso exponencial para los reintentos

4. Supervisa las cabeceras de límite de tasa

Manejo de errores

El servidor proporciona un manejo integral de errores para situaciones comunes:

• Errores de autenticación: tokens no válidos o caducados

• Errores de permisos: faltan permisos necesarios

• Limitación de tasa: reintento automático con retroceso

• Errores de red: tiempos de espera de conexión y reintentos

• Errores de API: respuestas de error específicas de Instagram

Consideraciones de seguridad

1. Seguridad de los tokens: almacena los tokens de acceso de forma segura

2. Variables de entorno: nunca subas tokens al control de versiones

3. Solo HTTPS: todas las llamadas a la API usan HTTPS

4. Renovación de tokens: implementa la renovación automática de tokens

5. Registro de auditoría: registra todas las interacciones con la API

Desarrollo

Estructura del proyecto

ig-mcp/
├── src/
│   ├── instagram_mcp_server.py    # Main MCP server
│   ├── instagram_client.py        # Instagram API client
│   ├── models/                    # Data models
│   ├── tools/                     # MCP tools implementation
│   ├── resources/                 # MCP resources implementation
│   └── prompts/                   # MCP prompts implementation
├── tests/                         # Unit and integration tests
├── config/                        # Configuration files
├── requirements.txt               # Python dependencies
├── .env.example                   # Environment variables template
└── README.md                      # This file

Ejecución de pruebas

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=src/

# Run specific test file
python -m pytest tests/test_instagram_client.py

Contribuciones

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)

3. Haz commit de tus cambios (git commit -m 'Add amazing feature')

4. Haz push a la rama (git push origin feature/amazing-feature)

5. Abre un Pull Request

Solución de problemas

Problemas comunes

1. "Invalid Access Token"

   • Verifica que el token no esté caducado

   • Comprueba los permisos del token

   • Regenera el token de larga duración

2. "Rate Limit Exceeded"

   • Espera a que se restablezca el límite de tasa

   • Implementa una cola de solicitudes

   • Usa solicitudes por lotes

3. "Permission Denied"

   • Verifica la configuración de la cuenta de Instagram Business

   • Comprueba la conexión con la página de Facebook

   • Revisa los permisos de la API

Modo de depuración

Habilita el registro de depuración estableciendo:

LOG_LEVEL=DEBUG

Licencia

Este proyecto está bajo la Licencia MIT; consulta el archivo LICENSE para obtener más detalles.

Soporte

• 📧 Correo electrónico: support@example.com

• 🐛 Problemas: GitHub Issues

• 📖 Documentación: Wiki

Agradecimientos

• Model Context Protocol de Anthropic

• Instagram Graph API de Meta

• FastMCP para el desarrollo rápido de MCP