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.

Conta Instagram Business ou Creator.
Em developers.facebook.com: criar um App, adicionar o produto Instagram e configurar Instagram Login (Business).
Solicitar as permissões instagram_business_content_publish e instagram_business_basic. Para uso em produção, passar pela App Review da Meta.
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

Aponte o Coolify para este repositório (build por Dockerfile ou docker-compose).
Defina um domínio público para o serviço (ex.: insta-mcp.duarteapps.cloud) — o Coolify já emite o TLS via Cloudflare.
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
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

instagram_get_account → confirma que a conta/token estão OK.
(IA gera a imagem/vídeo) → instagram_upload_media → recebe a url.
instagram_publish_image / _carousel / _reel com a url + caption.
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