Instagram

Servidor MCP do Instagram

Um servidor Model Context Protocol (MCP) que fornece integração perfeita com a API Graph do Instagram, permitindo que aplicações de IA interajam programaticamente com contas comerciais do Instagram.

Recursos

🔧 Ferramentas (controladas pelo modelo)

• Obter informações do perfil: Recuperar detalhes do perfil comercial do Instagram
• Obter publicações de mídia: Buscar publicações recentes de uma conta do Instagram
• Obter insights de mídia: Recuperar métricas de engajamento para publicações específicas
• Publicar mídia: Enviar e publicar imagens/vídeos no Instagram
• Obter páginas da conta: Listar páginas do Facebook conectadas à conta
• Obter conversas: Listar conversas de DM do Instagram (requer acesso avançado)
• Obter mensagens de conversa: Ler mensagens de conversas específicas (requer acesso avançado)
• Enviar DM: Responder a mensagens diretas do Instagram (requer acesso avançado)

📊 Recursos (controlados pela aplicação)

• Dados do perfil: Acesso a informações do perfil, incluindo contagem de seguidores, biografia, etc.
• Feed de mídia: Publicações recentes com métricas de engajamento
• Dados de insights: Análises detalhadas para publicações e desempenho da conta

💬 Prompts (controlados pelo usuário)

• Analisar engajamento: Prompt pré-construído para analisar o desempenho de publicações
• Estratégia de conteúdo: Modelo para gerar recomendações de conteúdo
• Análise de hashtags: Prompt para avaliação de desempenho de hashtags

Pré-requisitos

1. Conta comercial do Instagram: Deve estar conectada a uma página do Facebook
2. Conta de desenvolvedor do Facebook: Necessária para acesso à API
3. Token de acesso: Token de acesso de longa duração com as permissões apropriadas
4. Python 3.10+: Para executar o servidor MCP (exigido pelas dependências do MCP)

Permissões necessárias da API do Instagram

Acesso padrão (disponível imediatamente):

• 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

Acesso avançado (requer revisão do aplicativo Meta):

• instagram_manage_messages - Necessário para recursos de mensagens diretas

⚠️ Recursos de DM do Instagram: Ler e enviar mensagens diretas do Instagram requer aprovação de acesso avançado da Meta. Consulte INSTAGRAM_DM_SETUP.md para o processo de revisão do aplicativo.

🔑 Como obter credenciais da API do Instagram

📖 Início rápido: Consulte AUTHENTICATION_GUIDE.md para um guia de configuração de 5 minutos!

Esta seção fornece um guia passo a passo para obter as credenciais necessárias para o servidor MCP do Instagram.

Etapa 1: Configurar conta comercial do Instagram

1. Converter para conta comercial (se ainda não for):

   • Abra o aplicativo do Instagram → Configurações → Conta → Alternar para conta profissional
   • Escolha "Comercial" → Selecione uma categoria → Conclua a configuração

2. Conectar à página do Facebook:

   • Vá para Configurações do Instagram → Conta → Contas vinculadas → Facebook
   • Conecte-se a uma página existente do Facebook ou crie uma nova
   • Importante: A página do Facebook deve ser de sua propriedade

Etapa 2: Criar aplicativo do Facebook

1. Acesse Facebook Developers:

   • Visite developers.facebook.com
   • Faça login com sua conta do Facebook

2. Criar novo aplicativo:

   • Clique em "Criar aplicativo" → Escolha "Comercial" → Clique em "Avançar"
   • Preencha os detalhes do aplicativo:
     • Nome do aplicativo: Escolha um nome descritivo (por exemplo, "Meu servidor MCP do Instagram")
     • E-mail de contato do aplicativo: Seu endereço de e-mail
   • Clique em "Criar aplicativo"

3. Adicionar produto Instagram Basic Display:

   • No painel do seu aplicativo, clique em "Adicionar produto"
   • Encontre "Instagram Basic Display" → Clique em "Configurar"

4. Configurar Instagram Basic Display:

   • Vá para Instagram Basic Display → Basic Display
   • Clique em "Criar novo aplicativo" na seção de aplicativos do Instagram
   • Aceite os termos e crie o aplicativo

Etapa 3: Obter credenciais do aplicativo

1. Obter ID e segredo do aplicativo:
   • No painel do seu aplicativo do Facebook, vá para Configurações → Básico
   • Copie seu ID do aplicativo e Segredo do aplicativo
   • Importante: Mantenha o segredo do aplicativo seguro e nunca o compartilhe publicamente

Etapa 4: Configurar acesso à API comercial do Instagram

1. Adicionar produto Instagram Graph API:

   • No painel do seu aplicativo, clique em "Adicionar produto"
   • Encontre "Instagram Graph API" → Clique em "Configurar"

2. Configurar permissões:

   • Vá para Instagram Graph API → Permissões
   • Solicite as seguintes permissões:
     • instagram_basic
     • instagram_content_publish
     • instagram_manage_insights
     • pages_show_list
     • pages_read_engagement

Etapa 5: Gerar token de acesso

Opção A: Usando o Graph API Explorer do Facebook (recomendado para testes)

1. Acesse o Graph API Explorer:

   • Visite developers.facebook.com/tools/explorer

2. Configurar o Explorer:

   • Selecione seu aplicativo no menu suspenso
   • Clique em "Gerar token de acesso"
   • Selecione as permissões necessárias quando solicitado

3. Obter token de acesso da página:

   • No explorer, faça uma solicitação GET para: /me/accounts
   • Encontre sua página do Facebook na resposta
   • Copie o access_token para sua página

4. Obter ID da conta comercial do Instagram:

   • Use o token de acesso da página para fazer uma solicitação GET para: /{page-id}?fields=instagram_business_account
   • Copie o ID da conta comercial do Instagram da resposta

Opção B: Usando o fluxo de login do Facebook (recomendado para produção)

1. Configurar login do Facebook:

   • No painel do seu aplicativo, adicione o produto "Facebook Login"
   • Configure URIs de redirecionamento OAuth válidos

2. Implementar fluxo 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. Trocar código por 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}"
   

Etapa 6: Obter token de acesso de longa duração

Tokens de curta duração expiram em 1 hora. Converta para token de longa duração (60 dias):

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}"

Etapa 7: Configurar variáveis de ambiente

Crie um arquivo .env na raiz do seu projeto:

# 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

Etapa 8: Testar sua configuração

Execute o script de validação para testar suas credenciais:

python scripts/setup.py

Ou teste 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 importantes de segurança

1. Nunca envie credenciais para controle de versão
2. Use variáveis de ambiente ou gerenciamento seguro de segredos
3. Rotacione tokens de acesso regularmente
4. Monitore datas de expiração de tokens
5. Use apenas HTTPS em produção
6. Implemente tratamento adequado de erros para tokens expirados

🔄 Estratégia de renovação de token

Tokens de longa duração expiram após 60 dias. Implemente renovação 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')

📋 Solução de problemas comuns

Erro: "Token de acesso OAuth inválido"

• Verifique se o token expirou
• Verifique se o token tem as permissões necessárias
• Garanta que a conta do Instagram esteja conectada à página do Facebook

Erro: "Conta do Instagram não encontrada"

• Verifique se o ID da conta comercial do Instagram está correto
• Verifique se a conta do Instagram está vinculada corretamente à página do Facebook
• Garanta que a conta seja comercial, não pessoal

Erro: "Permissões insuficientes"

• Revise as permissões necessárias no aplicativo do Facebook
• Gere novamente o token de acesso com os escopos corretos
• Verifique se o aplicativo está em modo Desenvolvimento ou Ativo

Problemas de limite de taxa

• Implemente backoff exponencial
• Armazene respostas em cache quando possível
• Monitore cabeçalhos de limite de taxa nas respostas da API

Instalação

1. Clonar o repositório:

git clone <repository-url>
cd ig-mcp

2. Instalar dependências:

pip install -r requirements.txt

3. Configurar variáveis de ambiente:

cp .env.example .env
# Edit .env with your Instagram API credentials

4. Configurar o servidor MCP:

# Edit config.json with your specific settings

Configuração

Variáveis de ambiente (.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

Configuração do cliente MCP

Adicione isso à configuração do seu cliente MCP (por exemplo, Claude Desktop):

{
  "mcpServers": {
    "instagram": {
      "command": "python",
      "args": ["/path/to/ig-mcp/src/instagram_mcp_server.py"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Exemplos de uso

Usando com Claude Desktop

1. Obter informações do perfil:

Can you get my Instagram profile information?

2. Analisar publicações recentes:

Show me my last 5 Instagram posts and their engagement metrics

3. Publicar conteúdo:

Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"

Usando com cliente MCP 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 da API cobertos

Gerenciamento de perfil

• Obter informações do perfil comercial
• Atualizar detalhes do perfil (recurso futuro)

Gerenciamento de mídia

• Recuperar publicações recentes
• Obter detalhes específicos de mídia
• Enviar e publicar novo conteúdo
• Excluir mídia (recurso futuro)

Análises e insights

• Métricas de engajamento de publicações (curtidas, comentários, compartilhamentos)
• Insights da conta (alcance, impressões)
• Análise de desempenho de hashtags

Gerenciamento de conta

• Listar páginas do Facebook conectadas
• Alternar entre contas comerciais

Limite de taxa e melhores práticas

O servidor implementa limite de taxa inteligente para cumprir os limites da API do Instagram:

• Solicitações de perfil: 200 chamadas por hora
• Solicitações de mídia: 200 chamadas por hora
• Publicação: 25 publicações por dia
• Insights: 200 chamadas por hora

Melhores práticas

1. Armazene dados acessados com frequência em cache
2. Use solicitações em lote quando possível
3. Implemente backoff exponencial para novas tentativas
4. Monitore cabeçalhos de limite de taxa

Tratamento de erros

O servidor fornece tratamento abrangente de erros para cenários comuns:

• Erros de autenticação: Tokens inválidos ou expirados
• Erros de permissão: Permissões necessárias ausentes
• Limite de taxa: Nova tentativa automática com backoff
• Erros de rede: Timeouts de conexão e novas tentativas
• Erros de API: Respostas de erro específicas do Instagram

Considerações de segurança

1. Segurança do token: Armazene tokens de acesso com segurança
2. Variáveis de ambiente: Nunca envie tokens para controle de versão
3. Somente HTTPS: Todas as chamadas de API usam HTTPS
4. Renovação de token: Implemente renovação automática de tokens
5. Registro de auditoria: Registre todas as interações da API

Desenvolvimento

Estrutura do projeto

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

Executando testes

# 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

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de recurso (git checkout -b feature/amazing-feature)
3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
4. Envie para o branch (git push origin feature/amazing-feature)
5. Abra uma solicitação de pull

Solução de problemas

Problemas comuns

1. "Token de acesso inválido"

   • Verifique se o token não expirou
   • Verifique as permissões do token
   • Gere novamente o token de longa duração

2. "Limite de taxa excedido"

   • Aguarde a redefinição do limite de taxa
   • Implemente fila de solicitações
   • Use solicitações em lote

3. "Permissão negada"

   • Verifique a configuração da conta comercial do Instagram
   • Verifique a conexão da página do Facebook
   • Revise as permissões da API

Modo de depuração

Ative o registro de depuração definindo:

LOG_LEVEL=DEBUG

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Suporte

• 📧 E-mail: support@example.com
• 🐛 Problemas: GitHub Issues
• 📖 Documentação: Wiki

Agradecimentos

• Model Context Protocol por Anthropic
• Instagram Graph API por Meta
• FastMCP para desenvolvimento rápido de MCP