instagram-mcp

instagram-mcp

Um servidor Model Context Protocol que encapsula a Instagram Graph API para que o Claude (ou qualquer cliente MCP) possa ler, publicar, comentar, enviar DMs e obter insights de uma conta Business ou Creator do Instagram.

24 ferramentas em cinco áreas de capacidade — perfil/mídia, publicação, comentários, DMs e insights — construídas com FastMCP + httpx.

Instalação rápida

pip install instagram-mcp

Ou com uv:

uv tool install instagram-mcp

Configuração

1. Criar um aplicativo Meta

1. Acesse https://developers.facebook.com/apps → Criar aplicativo → caso de uso Outro → tipo Business.
2. No painel do aplicativo, adicione o produto Instagram (Adicionar produto → Instagram → Configurar).

2. Vincular uma conta Business/Creator do Instagram

Você precisa de uma conta do Instagram alternada para Business ou Creator, vinculada a uma Página do Facebook. No painel do aplicativo, siga Instagram → Configuração da API com login do Facebook → Etapa 1: Gerar tokens de acesso e vincule sua conta.

3. Obter as permissões necessárias

Gere um token com esses escopos (no Graph API Explorer ou na página de configuração da API do Instagram):

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

Enquanto seu aplicativo estiver em modo de desenvolvimento, apenas contas na lista de Funções do seu aplicativo (administradores/desenvolvedores/testadores) podem autenticar. Isso é suficiente para uso pessoal. Para outros usuários, você precisa da Revisão do aplicativo com Acesso Avançado.

4. Gerar um token de Página de longa duração

A maneira mais rápida: execute o auxiliar incluído.

instagram-mcp-get-token

Ele solicitará seu token de usuário de curta duração + ID/segredo do aplicativo, fará a troca por um token de usuário de longa duração, listará suas contas IG vinculadas e gravará o .env para você.

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"

Use o access_token da Página (nunca expira) e o instagram_business_account.id da conta IG vinculada.

5. Configurar .env

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

Defina IG_GRAPH_HOST=graph.instagram.com se o seu token veio do caminho Login do Instagram em vez do Login do Facebook.

Conectar ao Claude Desktop

Edite ~/.config/Claude/claude_desktop_config.json (Linux) ou ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Reinicie o Claude Desktop. Você deve ver 24 ferramentas no servidor instagram.

Ferramentas disponíveis

Perfil e mídia

Ferramenta	O que faz
get_my_profile	Informações do perfil: bio, seguidores, contagem de mídia, etc.
list_my_media	Uma página de postagens recentes
list_all_media	Paginação automática por toda a mídia
get_media	Buscar um único item de mídia
list_tagged_media	Postagens em que a conta foi marcada
list_stories	Stories ao vivo (janela de 24h)

Hashtags

Ferramenta	O que faz
search_hashtag	Resolver um #tag para o seu ID
hashtag_top_media	Postagens mais bem classificadas para uma hashtag
hashtag_recent_media	Postagens recentes para uma hashtag (janela de 24h)

Publicação

Ferramenta	O que faz
publish_image	Postagem de imagem única a partir de uma URL pública
publish_reel	Reel (aguarda o processamento do contêiner)
publish_story	Story de imagem ou vídeo
publish_carousel	Carrossel de 2 a 10 itens
get_publish_limit	Mostrar uso da cota de publicação de 24h

Comentários

Ferramenta	O que faz
list_comments	Comentários de nível superior + respostas aninhadas
get_comment_replies	Respostas sob um comentário específico
reply_to_comment	Publicar uma resposta
hide_comment	Ocultar / exibir
delete_comment	Excluir um comentário que você possui

Mensagens diretas

Ferramenta	O que faz
list_conversations	Conversas de DM
get_conversation	Mensagens em uma conversa
send_dm	Enviar uma DM (opcionalmente com um message_tag)

Insights

Ferramenta	O que faz
get_account_insights	Métricas de nível de conta com metric_type opcional
get_media_insights	Insights por mídia

Notas e pegadinhas

• A publicação requer URLs HTTPS públicas. O Meta busca a mídia no servidor. Hospede suas imagens/vídeos em uma URL publicamente acessível primeiro.
• A cota de publicação é de 100 postagens por janela contínua de 24h na maioria das contas Business.
• send_dm é somente resposta por padrão — só funciona dentro da janela de 24h iniciada pelo usuário. Passe um message_tag (ex.: HUMAN_AGENT) para enviar fora dessa janela. Tags exigem aprovação do Meta.
• Algumas métricas de insights precisam de metric_type='total_value' (o Meta endureceu isso em 2024): views, accounts_engaged, total_interactions, profile_views, likes, comments, shares, saves. reach e follower_count não precisam.
• Erros retornam um dicionário estruturado, não exceções. Procure por error: true junto com status, message, code, subcode e fbtrace_id na resposta — isso é o erro da Graph API, não um traceback do Python.

Desenvolvimento

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

Licença

MIT — veja LICENSE.