instagram-mcp-server

Servidor MCP para publicação automática no Instagram — imagem única, carrossel e Reels — via Instagram Graph API oficial. Projetado para ser operado por um agente (Claude) e rodar no Coolify.

O conteúdo (imagem/vídeo/legenda) é gerado por IA no momento da operação: o agente gera a mídia, hospeda com instagram_upload_media e publica com a tool correspondente. Cada tool executa o fluxo completo da Graph API (cria container → aguarda processamento → publica) em uma única chamada.

Tools expostas

Tool	Função
instagram_upload_media	Hospeda mídia (base64) e devolve URL pública temporária
instagram_publish_image	Publica 1 imagem no feed
instagram_publish_carousel	Publica carrossel (2–10 itens, imagem/vídeo)
instagram_publish_reel	Publica um Reel (vídeo)
instagram_get_account	Dados da conta conectada
instagram_publishing_limit	Cota de publicações nas últimas 24h (~50/dia)
instagram_refresh_token	Renova o long-lived token (~60 dias)

---

Pré-requisitos na Meta (fazer uma vez)

Este servidor usa por padrão a Instagram API with Instagram Login (token IGAA…, endpoint graph.instagram.com) — a rota moderna que dispensa Página do Facebook.

1. Conta Instagram Business ou Creator.
2. Em developers.facebook.com: criar um App, adicionar o produto Instagram e configurar Instagram Login (Business).
3. Solicitar as permissões instagram_business_content_publish e instagram_business_basic. Para uso em produção, passar pela App Review da Meta.
4. Gerar um long-lived access token (IGAA…) e anotar o Instagram User ID (via GET https://graph.instagram.com/v21.0/me?fields=user_id,username).

Guarde IG_USER_ID e IG_ACCESS_TOKEN.

Rota alternativa (Facebook Login): se preferir o token EAA… via Página do Facebook, defina IG_API_BASE=https://graph.facebook.com/v21.0 e siga o fluxo fb_exchange_token para o token.

---

Deploy no Coolify

1. Aponte o Coolify para este repositório (build por Dockerfile ou docker-compose).
2. Defina um domínio público para o serviço (ex.: insta-mcp.duarteapps.cloud) — o Coolify já emite o TLS via Cloudflare.
3. Configure as variáveis de ambiente (ver .env.example):
   • IG_USER_ID, IG_ACCESS_TOKEN
   • PUBLIC_BASE_URL = o domínio público acima (a Graph API baixa a mídia daqui)
   • MCP_AUTH_TOKEN = um token aleatório forte
   • (opcional) FB_APP_ID, FB_APP_SECRET para renovar o token
4. Garanta que a porta 3000 está exposta e o healthcheck aponta para /health.

O endpoint MCP fica em https://insta-mcp.duarteapps.cloud/mcp.

---

Conectar como MCP no Claude

Adicione um conector MCP HTTP:

• URL: https://insta-mcp.duarteapps.cloud/mcp
• Header: Authorization: Bearer <MCP_AUTH_TOKEN>

Teste rápido:

curl -X POST https://insta-mcp.duarteapps.cloud/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

---

Fluxo típico operado pelo agente

1. instagram_get_account → confirma que a conta/token estão OK.
2. (IA gera a imagem/vídeo) → instagram_upload_media → recebe a url.
3. instagram_publish_image / _carousel / _reel com a url + caption.
4. instagram_publishing_limit → confere a cota antes de lotes.

Requisitos de mídia (resumo)

• Imagem: JPG/PNG, 4:5 a 1.91:1, até 8 MB.
• Reel: MP4/MOV H.264, 3 s a 15 min, até ~1 GB, 9:16 recomendado.
• Carrossel: 2 a 10 itens.

Limitações da API (por design da Meta)

• Stories têm suporte limitado na Content Publishing API.
• Curtir, seguir, comentar e enviar DM automatizados são proibidos pelos Termos — não implementados aqui de propósito.
• ~50 publicações por conta a cada 24 h.

Desenvolvimento local

npm install
npm run build
MCP_AUTH_TOKEN=dev PUBLIC_BASE_URL=http://localhost:3000 \
IG_USER_ID=... IG_ACCESS_TOKEN=... npm start