instagram-mcp

instagram-mcp

Un servidor de Model Context Protocol que envuelve la Instagram Graph API para que Claude (o cualquier cliente MCP) pueda leer, publicar, comentar, enviar mensajes directos y obtener información de una cuenta de Instagram Empresa o Creador.

24 herramientas en cinco áreas de capacidad: perfil/medios, publicación, comentarios, mensajes directos e información, construido sobre FastMCP + httpx.

Instalación rápida

pip install instagram-mcp

O con uv:

uv tool install instagram-mcp

Configuración

1. Crear una aplicación de Meta

1. Ve a https://developers.facebook.com/apps → Crear aplicación → caso de uso Otro → tipo Empresa.
2. En el panel de la aplicación, agrega el producto Instagram (Agregar producto → Instagram → Configurar).

2. Vincular una cuenta de Instagram Empresa/Creador

Necesitas una cuenta de Instagram configurada como Empresa o Creador, vinculada a una Página de Facebook. En el panel de la aplicación, sigue Instagram → Configuración de API con inicio de sesión de Facebook → Paso 1: Generar tokens de acceso y vincula tu cuenta.

3. Obtener los permisos necesarios

Genera un token con estos alcances (en el Explorador de Graph API o en la página de configuración de la API de Instagram):

• instagram_basic
• instagram_content_publish
• instagram_manage_comments
• instagram_manage_messages
• instagram_manage_insights
• pages_show_list
• pages_read_engagement
• business_management

Mientras tu aplicación esté en modo de desarrollo, solo las cuentas en la lista de Roles de tu aplicación (administradores/desarrolladores/probadores) pueden autenticarse. Eso es suficiente para uso personal. Para otros usuarios, necesitas Revisión de la aplicación con Acceso avanzado.

4. Generar un token de Página de larga duración

La forma más rápida: ejecuta el asistente incluido.

instagram-mcp-get-token

Te pedirá tu token de usuario de corta duración + ID/secreto de la aplicación, lo intercambiará por un token de usuario de larga duración, listará tus cuentas de IG vinculadas y escribirá .env por ti.

Alternativa manual:

# Exchange short-lived user token → long-lived (~60 days)
curl -G "https://graph.facebook.com/v21.0/oauth/access_token" \
  --data-urlencode "grant_type=fb_exchange_token" \
  --data-urlencode "client_id=YOUR_APP_ID" \
  --data-urlencode "client_secret=YOUR_APP_SECRET" \
  --data-urlencode "fb_exchange_token=SHORT_LIVED_TOKEN"

# Find your Pages and their IG accounts
curl -G "https://graph.facebook.com/v21.0/me/accounts" \
  --data-urlencode "fields=name,instagram_business_account,access_token" \
  --data-urlencode "access_token=LONG_LIVED_USER_TOKEN"

Usa el access_token de la Página (nunca expira) y el instagram_business_account.id de la cuenta de IG vinculada.

5. Configurar .env

IG_USER_ID=17841446575432302
IG_ACCESS_TOKEN=EAAxxxxxxxxxxxxxxxxxxx
IG_GRAPH_VERSION=v21.0
IG_GRAPH_HOST=graph.facebook.com

Establece IG_GRAPH_HOST=graph.instagram.com si tu token proviene de la ruta de Inicio de sesión de Instagram en lugar de Inicio de sesión de Facebook.

Conectar a Claude Desktop

Edita ~/.config/Claude/claude_desktop_config.json (Linux) o ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "instagram": {
      "command": "instagram-mcp",
      "env": {
        "IG_USER_ID": "17841446575432302",
        "IG_ACCESS_TOKEN": "EAAxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Reinicia Claude Desktop. Deberías ver 24 herramientas bajo el servidor instagram.

Herramientas disponibles

Perfil y medios

Herramienta	Qué hace
get_my_profile	Información del perfil: biografía, seguidores, recuento de medios, etc.
list_my_media	Una página de publicaciones recientes
list_all_media	Paginación automática a través de todos los medios
get_media	Obtener un solo elemento de medio
list_tagged_media	Publicaciones en las que la cuenta está etiquetada
list_stories	Historias actualmente en vivo (ventana de 24 h)

Hashtags

Herramienta	Qué hace
search_hashtag	Resolver un #tag a su ID
hashtag_top_media	Publicaciones mejor clasificadas para un hashtag
hashtag_recent_media	Publicaciones recientes para un hashtag (ventana de 24 h)

Publicación

Herramienta	Qué hace
publish_image	Publicación de imagen única desde una URL pública
publish_reel	Reel (espera el procesamiento del contenedor)
publish_story	Historia de imagen o video
publish_carousel	Carrusel de 2 a 10 elementos
get_publish_limit	Mostrar uso de cuota de publicación de 24 h

Comentarios

Herramienta	Qué hace
list_comments	Comentarios de nivel superior + respuestas anidadas
get_comment_replies	Respuestas bajo un comentario específico
reply_to_comment	Publicar una respuesta
hide_comment	Ocultar / mostrar
delete_comment	Eliminar un comentario que posees

Mensajes directos

Herramienta	Qué hace
list_conversations	Conversaciones de mensajes directos
get_conversation	Mensajes en una conversación
send_dm	Enviar un mensaje directo (opcionalmente con un message_tag)

Insights

Herramienta	Qué hace
get_account_insights	Métricas a nivel de cuenta con metric_type opcional
get_media_insights	Información por medio

Notas y advertencias

• La publicación requiere URLs HTTPS públicas. Meta obtiene los medios del lado del servidor. Aloja tus imágenes/videos en una URL públicamente accesible primero.
• La cuota de publicación es de 100 publicaciones por ventana móvil de 24 h en la mayoría de las cuentas de Empresa.
• send_dm es solo de respuesta por defecto — solo funciona dentro de la ventana de 24 h iniciada por el usuario. Pasa un message_tag (por ejemplo, HUMAN_AGENT) para enviar fuera de esa ventana. Las etiquetas requieren aprobación de Meta.
• Algunas métricas de información necesitan metric_type='total_value' (Meta lo endureció en 2024): views, accounts_engaged, total_interactions, profile_views, likes, comments, shares, saves. reach y follower_count no.
• Los errores devuelven un dict estructurado, no excepciones. Busca error: true junto con status, message, code, subcode y fbtrace_id en la respuesta: ese es el error de Graph API, no un traceback de Python.

Desarrollo

git clone https://github.com/AleemHaider/instagram-mcp
cd instagram-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Licencia

MIT — ver LICENCIA.