mcp-email-instagram
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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: universal-email-mcp
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
Ferramenta | O que faz | Tipo |
| Lista as pastas, com os marcadores especiais (Enviados, Lixeira, Rascunhos) | leitura |
| Busca por remetente, assunto, texto, período, não lidas; no Gmail, aceita a sintaxe de busca dele | leitura |
| Cabeçalhos, corpo em texto (HTML convertido) e lista de anexos, sem marcar como lido | leitura |
| Salva um anexo localmente | escrita |
| Envia, inclusive respondendo no mesmo fio ( | escrita |
| Grava rascunho sem enviar | escrita |
| Move entre pastas; marca lida/não lida, sinalizada | escrita |
| Manda para a Lixeira; apaga em definitivo só se pedido | destrutiva |
| Perfil, seguidores e posts com curtidas e comentários | leitura |
| Alcance, visualizações, visitas ao perfil, interações | leitura |
| Comentários de um post e o Direct | leitura |
| Responde ou oculta comentário | escrita |
| Responde no Direct, só dentro da janela de 24h | escrita |
| Publica imagem, carrossel (2 a 10) ou Reels | escrita |
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
httpxregistra 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 emAuthorization: Bearer, os loggershttpx/httpcoreficam em WARNING, e há teste para as duas coisas. Vejainstagram.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 comINSTAGRAM_LOGIN=facebook.Sem conversa fria no Direct. A Meta só permite responder até 24h depois da última mensagem da pessoa.
ig_enviar_dmconfere 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(ouFrom), o assunto ganhaRe:uma vez só, eIn-Reply-To/Referencessã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 enviadose a Hostinger deINBOX.Sent.Busca com acento vai como literal UTF-8 no fim do comando.
A data do
SINCEnão usastrftime('%b'), que segue o locale da máquina: em português sairiasete o servidor recusa.Com
UIDPLUS, o expurgo éUID EXPUNGE. Sem ele, oEXPUNGEcomum 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 umSMTPRecipientsRefused({})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 # opcionalO 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).
Crie um app do tipo Empresa em developers.facebook.com.
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.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.
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-instagramClaude 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.
Variável | Para quê |
| Nomes das caixas, separados por vírgula; a primeira é a padrão |
| Credenciais e servidores de cada caixa (portas padrão 993 e 465) |
|
|
|
|
| Gravados pelo assistente de configuração |
| Só no modo |
| Texto somado às instruções que o modelo recebe (tom de voz, o que não prometer) |
| Pasta de dados (padrão |
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 saemTestes
uv run --group dev pytest -vOs 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
getaddressesestrito);a trava de 24h do Direct (conversa fria, fora da janela, dentro dela);
o token fora da URL e o log do
httpxcalado;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
FastMCPparaMCPServere mudou a API. O projeto fixamcp<2até 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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Instagram for AI agents: publish, read comments and DMs, insights, and engage from your account.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Instagram and Facebook Pages for AI agents: publish, comments, DM by keyword, inbox, insights.
Related MCP Servers
- AlicenseAqualityBmaintenanceYour real mailbox and calendar for your AI agent — Microsoft 365 via Graph or any IMAP — as 24 tools: read, search, attachments as text, sender history, drafting from identity and knowledge files, free-slot computation. Send, reply, delete and calendar writes need out-of-band human approval: the agent cannot approve its own actions.44117 PyPI20AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to search, retrieve, and send email across multiple ordinary IMAP, POP3, and SMTP mailboxes, with per-account permissions and safe sending checks.20 PyPIApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to triage and act on Instagram DMs, comments, and mentions with token-light overviews, unread lists, search, thread summaries, drafting replies or moderation actions, and human-approved sending.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to read, search, send, and organize email over IMAP and SMTP for providers such as Gmail, Yahoo, iCloud, Zoho, Fastmail, and custom domains, with tools for attachments, drafts, templates, scheduling, and safe mailbox management.28 npmMIT