mcp-email-instagram

Servidor MCP (Model Context Protocol) em Python que dá a assistentes de IA acesso a caixas de e-mail (qualquer provedor IMAP/SMTP, uma ou várias) e a uma conta profissional do Instagram, pela API oficial da Meta.

Com ele conectado, você pede ao Claude (ou a qualquer cliente MCP) coisas como:

"Tem e-mail de cliente sem resposta desde segunda? Rascunha uma resposta para cada um."

"Quantas pessoas visitaram o perfil do Instagram esta semana? E qual post teve mais alcance?"

"Responde o comentário do último post agradecendo, e oculta o que é spam."

e o modelo chama as ferramentas certas em vez de pedir para você copiar e colar.

Em resumo:

• 20 ferramentas: 9 de e-mail e 11 de Instagram.

• Travas no servidor, não no prompt: a DM só sai dentro de 24h, o token nunca aparece em URL e toda escrita fica registrada.

• Segredos só na sua máquina: o modelo nunca vê senha nem token.

• 27 testes sem rede, rodando no CI em Python 3.11, 3.12 e 3.13.

Como funciona

Related MCP server: gigamail

Na prática

Um pedido vira uma sequência de chamadas. As de leitura correm soltas, as de escrita ficam registradas, e o que a regra não permite é recusado antes de chegar à API:

As duas imagens são geradas de HTML: docs/como-funciona.html e docs/exemplo-conversa.html.

Ferramentas

Cada ferramenta declara ao cliente se é somente leitura, destrutiva ou idempotente (ToolAnnotations). O cliente usa isso para decidir quando pedir confirmação.

Decisões de implementação

• Token no cabeçalho, nunca na URL. O httpx registra a URL completa em nível INFO, e servidores MCP costumam ligar o log nesse nível. Com o token na query string, ele vai parar no log do cliente. Descobri isso num teste real. Agora o token vai em Authorization: Bearer, os loggers httpx/httpcore ficam em WARNING, e há teste para as duas coisas. Veja instagram.graph.

• Instagram sem Facebook. O caminho padrão é a API do Instagram com login do Instagram (graph.instagram.com), que não exige conta no Facebook nem Página vinculada. O token vale 60 dias, e o servidor renova sozinho depois de 20 (a Meta só renova token com mais de 24h), regravando o .env. O caminho antigo, por token de Página, continua disponível com INSTAGRAM_LOGIN=facebook.

• Sem conversa fria no Direct. A Meta só permite responder até 24h depois da última mensagem da pessoa. ig_enviar_dm confere isso antes de chamar a API: o modelo não consegue iniciar conversa, mesmo que alguém peça. Automação de navegador ficou de fora de propósito, porque viola os termos e dispara o "confirme que você é humano" na conta.

• Resposta no mesmo fio. Ao responder, o destinatário vem do Reply-To (ou From), o assunto ganha Re: uma vez só, e In-Reply-To/References são montados a partir do original. Sem isso, cada resposta abre uma conversa nova no cliente de e-mail de quem recebe.

• IMAP que funciona em servidor real.

  • Tudo é feito por UID, que não muda quando outras mensagens são apagadas.

  • As pastas especiais são achadas pelo marcador SPECIAL-USE (RFC 6154), com plano B pelo nome, porque o Gmail chama a de enviados de [Gmail]/E-mails enviados e a Hostinger de INBOX.Sent.

  • Busca com acento vai como literal UTF-8 no fim do comando.

  • A data do SINCE não usa strftime('%b'), que segue o locale da máquina: em português sairia set e o servidor recusa.

  • Com UIDPLUS, o expurgo é UID EXPUNGE. Sem ele, o EXPUNGE comum levaria junto qualquer mensagem já marcada para exclusão na pasta.

• Destinatários sem cabeçalho vazio. Desde a correção do CVE-2023-27043 (Python 3.12+ e também as versões de segurança do 3.11), getaddresses(['a@x.com', '', '']) devolve [('', '')]: um Cc ou Cco vazio na lista zera todos os destinatários, e o SMTP recusa com um SMTPRecipientsRefused({}) que aparece só como {}. Só os cabeçalhos preenchidos entram na conta. O primeiro envio real pegou isso, e há teste de regressão para os três casos.

• Cópia em Enviados sem duplicar. O SMTP não guarda cópia. O servidor grava em Enviados por IMAP, exceto no Gmail, que já faz isso sozinho e ficaria com duas cópias.

• Trilha de auditoria. Toda ação que escreve (enviar, apagar, mover, publicar, responder, renovar token) vira uma linha em auditoria.jsonl. Leitura não é registrada.

• Segredo não passa pelo modelo. Senhas e tokens são digitados no terminal pelo assistente de configuração (getpass), testados contra o servidor e só então gravados. Nenhuma ferramenta recebe credencial como parâmetro.

Como rodar

Requisitos: uv e Python 3.11+.

git clone https://github.com/ronnyarruda20/mcp-email-instagram
cd mcp-email-instagram
uv run mcp-email-instagram-configurar email       # uma vez por caixa
uv run mcp-email-instagram-configurar instagram   # opcional

O assistente grava tudo em ~/.mcp-email-instagram/.env, fora do repositório.

Gmail: com a verificação em duas etapas ligada, crie uma senha de app em myaccount.google.com/apppasswords. A senha normal é recusada por IMAP.

Instagram: a conta precisa ser profissional (Empresa ou Criador).

1. Crie um app do tipo Empresa em developers.facebook.com.

2. Adicione o caso de uso Gerenciar mensagens e conteúdo no Instagram e, em Permissões e recursos, as permissões instagram_business_* que for usar.

3. Em Configuração da API com login do Instagram, clique em Adicionar conta. A conta entra como Testador do Instagram; aceite o convite em instagram.com → Configurações → Apps e sites.

4. Clique em Gerar token.

Como dono do app e da conta, você usa o acesso padrão, sem App Review. Para o Direct, ligue Permitir acesso às mensagens nas configurações de mensagens do Instagram.

Conectando a um assistente

Claude Code:

claude mcp add email-instagram -- uv run --project /caminho/para/mcp-email-instagram mcp-email-instagram

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "email-instagram": {
      "command": "uv",
      "args": ["run", "--project", "/caminho/para/mcp-email-instagram", "mcp-email-instagram"]
    }
  }
}

Configuração

Tudo por variável de ambiente ou pelo .env da pasta de dados. O ambiente vence o arquivo. Modelo completo em .env.example.

Estrutura

src/mcp_email_instagram/
├── servidor.py      # as 20 ferramentas MCP: nome, descrição, parâmetros e anotações
├── email_imap.py    # IMAP/SMTP: busca, leitura, envio, resposta no fio, pastas especiais
├── instagram.py     # Graph API: token no cabeçalho, renovação, trava de 24h, publicação
├── config.py        # .env, caixas de e-mail, pasta de dados
├── auditoria.py     # auditoria.jsonl de toda ação que escreve
└── configurar.py    # assistente de terminal que testa e grava as credenciais
tests/               # IMAP, SMTP e Meta falsos: nada sai para a rede
docs/                # imagens do README e o HTML de onde saem

Testes

uv run --group dev pytest -v

Os testes não usam rede: IMAP, SMTP e Graph API são substituídos por versões falsas que registram cada comando. Eles cobrem:

• o encadeamento da resposta;

• a ordem dos critérios de busca com acento;

• a escolha de gravar ou não a cópia enviada;

• destinatários preservados com Cc e Cco vazios (regressão do getaddresses estrito);

• a trava de 24h do Direct (conversa fria, fora da janela, dentro dela);

• o token fora da URL e o log do httpx calado;

• a renovação do token aos 20 dias;

• a publicação de carrossel;

• as anotações de cada ferramenta.

O CI roda em Python 3.11, 3.12 e 3.13.

Limitações

• SDK MCP 1.x. A versão 2 renomeou FastMCP para MCPServer e mudou a API. O projeto fixa mcp<2 até a migração.

• Gmail por senha de app, não OAuth. É o caminho mais simples para uso pessoal. Para distribuir a terceiros, o certo seria OAuth com escopo restrito.

• Métricas do Instagram mudam de nome entre versões da Graph API. Se uma for recusada, o erro diz qual, e basta tirá-la da lista.

• Publicação exige URL pública da mídia: a Meta baixa o arquivo de lá. Upload de arquivo local não é suportado.

• Token vazado não se revoga individualmente. Remover o app da conta só suspende o token; reautorizar o app ressuscita os antigos.

Stack

Python 3.11+ · MCP Python SDK (FastMCP) · httpx · imaplib/smtplib da biblioteca padrão · pytest · uv · GitHub Actions

Licença

MIT