Instagram

Interactúa con cuentas de negocio de Instagram usando la API de Graph de Instagram.

GitHub
178
Prueba este MCPPatrocinado

Documentación

Verified on MseeP

MSeeP.ai Security Assessment Badge

Instagram MCP Server

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

Características

🔧 Herramientas (controladas por el modelo)

  • Get Profile Info: Recupera los detalles del perfil de negocio de Instagram
  • Get Media Posts: Obtiene las publicaciones recientes de una cuenta de Instagram
  • Get Media Insights: Recupera las métricas de interacción de publicaciones específicas
  • Publish Media: Sube y publica imágenes/videos en Instagram
  • Get Account Pages: Lista las páginas de Facebook conectadas a la cuenta
  • Get Conversations: Lista las conversaciones de DM de Instagram (requiere Acceso Avanzado)
  • Get Conversation Messages: Lee los mensajes de conversaciones específicas (requiere Acceso Avanzado)
  • Send DM: Responde a los mensajes directos de Instagram (requiere Acceso Avanzado)

📊 Recursos (controlados por la aplicación)

  • Profile Data: Acceso a la información del perfil, incluyendo número de seguidores, biografía, etc.
  • Media Feed: Publicaciones recientes con métricas de interacción
  • Insights Data: Análisis detallados para publicaciones y 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 la evaluación del rendimiento de hashtags

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 requeridos 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 de 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 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 MCP de Instagram.

Paso 1: Configurar la cuenta de Instagram Business

  1. Convertir a cuenta 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. Conectar a 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 de tu propiedad

Paso 2: Crear la aplicación de Facebook

  1. Ir a Facebook Developers:

  2. Crear nueva aplicación:

    • Haz clic en "Create App" → Elige "Business" → Haz clic en "Next"
    • Completa los detalles de la aplicación:
      • App Name: Elige un nombre descriptivo (por ejemplo, "My Instagram MCP Server")
      • App Contact Email: Tu dirección de correo electrónico
    • Haz clic en "Create App"

  3. Agregar el producto Instagram Basic Display:

    • En el panel de tu aplicación, haz clic en "Add Product"
    • Busca "Instagram Basic Display" → Haz clic en "Set Up"

  4. Configurar Instagram Basic Display:

    • Ve a Instagram Basic Display → Basic Display
    • Haz clic en "Create New App" en la sección de Instagram App
    • Acepta los términos y crea la aplicación

Paso 3: Obtener las credenciales de la aplicación

  1. Obtener App ID y App Secret:
    • En el panel de tu aplicación de Facebook, ve a Settings → Basic
    • Copia tu App ID y App Secret
    • Importante: Mantén el App Secret seguro y nunca lo compartas públicamente

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

  1. Agregar el producto Instagram Graph API:

    • En el panel de tu aplicación, haz clic en "Add Product"
    • Busca "Instagram Graph API" → Haz clic en "Set Up"

  2. Configurar permisos:

    • Ve a Instagram Graph API → Permissions
    • 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: Usando el Explorador de la API Graph de Facebook (recomendado para pruebas)

  1. Ir al Explorador de la API Graph:

  2. Configurar el explorador:

    • Selecciona tu aplicación en el menú desplegable
    • Haz clic en "Generate Access Token"
    • Selecciona los permisos requeridos cuando se te solicite

  3. Obtener el token de acceso de la página:

    • En el explorador, haz una solicitud GET a: /me/accounts
    • Encuentra tu página de Facebook en la respuesta
    • Copia el access_token para tu página

  4. Obtener 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: Usando el flujo de inicio de sesión de Facebook (recomendado para producción)

  1. Configurar Facebook Login:

    • En el panel de tu aplicación, agrega el producto "Facebook Login"
    • Configura las URI de redirección OAuth válidas

  2. Implementar el flujo 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. Intercambiar 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 expiran en 1 hora. Convierte a token 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 tu configuración

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

python scripts/setup.py

O prueba 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 gestión segura de secretos
  3. Rota los tokens de acceso regularmente
  4. Monitorea las fechas de expiración de los tokens
  5. Usa solo HTTPS en producción
  6. Implementa un manejo adecuado de errores para tokens expirados

🔄 Estrategia de renovación de tokens

Los tokens de larga duración expiran después de 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"

  • Verifica si el token ha expirado
  • Verifica que el token tenga los permisos requeridos
  • 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á vinculada correctamente a la página de Facebook
  • Asegúrate de que la cuenta sea Business, no Personal

Error: "Insufficient permissions"

  • Revisa los permisos requeridos en la aplicación de Facebook
  • Regenera el token de acceso con los alcances correctos
  • Comprueba si la aplicación está en modo Desarrollo o en modo Activo

Problemas de límite de velocidad (rate limiting)

  • Implementa retroceso exponencial (exponential backoff)
  • Almacena en caché las respuestas cuando sea posible
  • Monitorea los encabezados de límite de velocidad en las respuestas de la API

Instalación

  1. Clonar el repositorio:
git clone <repository-url>
cd ig-mcp
  1. Instalar dependencias:
pip install -r requirements.txt
  1. Configurar las variables de entorno:
cp .env.example .env
# Edit .env with your Instagram API credentials
  1. Configurar 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

Agrega esto a la configuración de tu cliente MCP (por ejemplo, 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

Usando con Claude Desktop

  1. Obtener información del perfil:
Can you get my Instagram profile information?
  1. Analizar publicaciones recientes:
Show me my last 5 Instagram posts and their engagement metrics
  1. Publicar contenido:
Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"

Usando 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 detalles del perfil (función futura)

Gestión de medios

  • Recuperar publicaciones recientes
  • Obtener detalles de medios específicos
  • Subir y publicar contenido nuevo
  • Eliminar medios (función futura)

Analítica e información

  • Métricas de interacción de publicaciones (me gusta, comentarios, compartidos)
  • Información de la cuenta (alcance, impresiones)
  • Análisis del rendimiento de hashtags

Gestión de cuentas

  • Listar páginas de Facebook conectadas
  • Cambiar entre cuentas de negocio

Límites de velocidad y mejores prácticas

El servidor implementa límites de velocidad inteligentes 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 por día
  • Insights: 200 llamadas por hora

Mejores prácticas

  1. Almacena en caché los datos de acceso frecuente
  2. Usa solicitudes por lotes cuando sea posible
  3. Implementa retroceso exponencial para reintentos
  4. Monitorea los encabezados de límite de velocidad

Manejo de errores

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

  • Errores de autenticación: Tokens inválidos o expirados
  • Errores de permisos: Faltan permisos requeridos
  • Límite de velocidad: 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 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

Ejecutar 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. Sube 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 haya expirado
    • 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 velocidad
    • Implementa cola de solicitudes
    • Usa solicitudes por lotes

  3. "Permission Denied"

    • Verifica la configuración de la cuenta de Instagram Business
    • Comprueba la conexión de la página de Facebook
    • Revisa los permisos de la API

Modo de depuración

Habilita el registro de depuración configurando:

LOG_LEVEL=DEBUG

Licencia

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

Soporte

Agradecimientos