simple-email-mcp

Servidor MCP de e-mail multi-contas extremamente simples — IMAP/SMTP, anexos, HTML, convites de calendário, envio opcional com trava. Funciona com qualquer provedor.

GitHub

Experimente este MCPPatrocinado

Documentação

simple-email-mcp

Um servidor MCP agnóstico de provedor para e-mail (IMAP/SMTP). Funciona com qualquer provedor de e-mail — Purelymail, Gmail, Outlook, DomainFactory ou qualquer servidor IMAP/SMTP padrão.

Desenvolvido para Claude Desktop, Claude Code e qualquer cliente compatível com MCP.

Recursos

Multi-contas — gerencie várias contas de e-mail de diferentes provedores
Ler, pesquisar, listar — suporte completo a IMAP com navegação por pastas
Enviar e-mails — texto simples, HTML ou ambos (multipart/alternative)
Anexos — envie via caminho de arquivo ou dados inline codificados em base64
Baixar anexos — extraia anexos de e-mails recebidos como base64
Convites de calendário — envie convites ICS adequados com botões Aceitar/Recusar
Salvar em Enviados — salva automaticamente e-mails enviados na pasta Enviados via IMAP
Portão de envio opcional — código de confirmação configurável para evitar envios acidentais
Pastas internacionais — lida com nomes de pastas codificados em UTF-7 (alemão, etc.)
Superfície MCP compacta — uma ferramenta email com descoberta de ações preguiçosa para reduzir o uso de contexto do cliente

Início rápido

1. Instalação

pip install simple-email-mcp

Ou a partir do código-fonte:

git clone https://github.com/mexican75/simple-email-mcp.git
cd simple-email-mcp
pip install .

2. Crie `accounts.json`

{
  "accounts": [
    {
      "name": "personal",
      "address": "me@example.com",
      "password": "your-app-password",
      "provider": "gmail"
    }
  ]
}

3. Adicione ao seu cliente

Claude Code (global, todos os projetos):

claude mcp add email -s user -e ACCOUNTS_FILE=/path/to/accounts.json -- simple-email-mcp

Claude Desktop — adicione à configuração (~/Library/Application Support/Claude/claude_desktop_config.json no macOS, %APPDATA%\Claude\claude_desktop_config.json no Windows):

{
  "mcpServers": {
    "email": {
      "command": "simple-email-mcp"
    }
  }
}

Ou se estiver executando a partir do código-fonte:

{
  "mcpServers": {
    "email": {
      "command": "python",
      "args": ["/path/to/simple_email_mcp.py"]
    }
  }
}

4. Reinicie seu cliente

Configuração

accounts.json

{
  "send_code": "MYSECRETCODE",
  "accounts": [
    {
      "name": "work",
      "address": "me@company.com",
      "send_as": "alias@company.com",
      "display_name": "Jane Doe",
      "description": "Primary work mailbox",
      "password": "app-password",
      "provider": "outlook"
    },
    {
      "name": "personal",
      "address": "me@gmail.com",
      "password": "app-password",
      "provider": "gmail"
    },
    {
      "name": "custom",
      "address": "me@mydomain.com",
      "password": "password",
      "imap_host": "mail.mydomain.com",
      "imap_port": 993,
      "smtp_host": "mail.mydomain.com",
      "smtp_port": 587,
      "smtp_security": "starttls"
    }
  ]
}

A configuração é recarregada a cada chamada de ferramenta, portanto alterações em accounts.json, como a rotação de send_code, entram em vigor sem reiniciar o servidor MCP.

Campos

Campo	Obrigatório	Descrição
`send_code`	Não	Se definido, os usuários devem fornecer este código para enviar e-mails. Omita ou defina como `""` para desativar.
`name`	Sim	Identificador curto para a conta (usado em chamadas de ferramenta)
`address`	Sim	Endereço de e-mail usado para login IMAP/SMTP
`send_as`	Não	Endereço de alias a ser usado como endereço `From`, remetente do envelope SMTP e domínio do Message-ID. O padrão é `address`. O alias deve ser autorizado pelo seu provedor de e-mail.
`display_name` / `from_name`	Não	Nome amigável do remetente usado no cabeçalho `From`, ex.: `Jane Doe <alias@example.com>`
`description`	Não	Rótulo legível por humanos exibido pela ação `list_accounts` para ajudar os clientes a escolher a caixa de correio correta
`password`	Sim	Senha ou senha específica do aplicativo
`provider`	Não	Predefinição: `gmail`, `outlook`, `purelymail`, `domainfactory`
`imap_host`	Não	Servidor IMAP personalizado (substitui o padrão do provedor)
`imap_port`	Não	Porta IMAP personalizada (padrão: 993)
`smtp_host`	Não	Servidor SMTP personalizado (substitui o padrão do provedor)
`smtp_port`	Não	Porta SMTP personalizada (padrão: 465)
`smtp_security`	Não	`ssl` (porta 465) ou `starttls` (porta 587). Detectado automaticamente pela porta se omitido.

Variáveis de ambiente (conta única)

Em vez de accounts.json, você pode configurar uma única conta por meio de variáveis de ambiente:

EMAIL_ADDRESS=me@example.com
EMAIL_PASSWORD=password
IMAP_HOST=imap.example.com
SMTP_HOST=smtp.example.com
SMTP_SECURITY=ssl
SEND_AS=alias@example.com
EMAIL_DISPLAY_NAME="Jane Doe"
EMAIL_DESCRIPTION="Primary mailbox"
SEND_CODE=optional

Ferramentas

A versão 2 expõe uma única ferramenta MCP chamada email. Chame-a apenas com um action para descobrir os parâmetros dessa ação e, em seguida, chame-a novamente com params.

{"action": "send"}

{
  "action": "send",
  "params": {
    "account": "work",
    "to": "recipient@example.com",
    "subject": "Hello",
    "body": "Message body"
  }
}

Ação	Descrição
`validate_config`	Valida a configuração sem fazer login em IMAP/SMTP
`list_accounts`	Lista as contas configuradas
`list_folders`	Lista as pastas IMAP de uma conta
`list_emails`	Lista e-mails recentes em uma pasta
`search`	Pesquisa e-mails usando critérios IMAP
`read`	Lê o conteúdo completo do e-mail por UID
`get_attachment`	Baixa um anexo como base64
`prepare_attachments`	Inspeciona caminhos de anexos locais antes do envio
`save_attachment`	Salva um anexo diretamente no disco (preferido para arquivos grandes)
`send`	Envia um e-mail (texto, HTML, anexos, convites de calendário)
`reply`	Responde a um e-mail (define automaticamente destinatário, assunto, encadeamento, cita o corpo)
`reply_all`	Responder a todos (remetente em Para, outros destinatários em CC, cita o corpo)
`forward`	Encaminha um e-mail com os anexos originais
`move`	Move um e-mail entre pastas
`mark`	Marca como lido/não lido/com sinalização/sem sinalização

list_accounts retorna os nomes exatos das contas, além de qualquer send_as, display_name e description configurados, para que os clientes possam usar o token de conta explícito em vez de adivinhar correspondências parciais.

Validação de configuração

Use validate_config após editar accounts.json ou variáveis de ambiente. Ele verifica campos obrigatórios, endereços com formato de e-mail, portas, segurança SMTP, provedores e hosts de espaço reservado, sem expor senhas ou fazer login em IMAP/SMTP.

{
  "action": "validate_config",
  "params": {}
}

Migrando da v1

A maioria dos usuários não precisa alterar a configuração do cliente MCP. Mantenha o mesmo comando simple-email-mcp e reinicie o cliente após a atualização.

A mudança significativa afeta apenas clientes ou scripts que chamam nomes exatos de ferramentas da v1, como email_send_email ou email_read_email. Na v2, use a única ferramenta email com uma ação:

Ferramenta v1	Ação v2
`email_list_accounts`	`email` com `action: "list_accounts"`
`email_send_email`	`email` com `action: "send"`
`email_read_email`	`email` com `action: "read"`
`email_search_emails`	`email` com `action: "search"`
`email_forward`	`email` com `action: "forward"`
`email_reply_all`	`email` com `action: "reply_all"`

Envio com anexos

Apenas metadados de pré-verificação (recomendado antes do envio):

attachments: "/path/to/file.pdf, /path/to/doc.xlsx"

Chame prepare_attachments primeiro para verificar caminhos resolvidos, nomes de arquivos, tamanhos, tipos MIME e arquivos ausentes, sem carregar conteúdos no contexto.

Caminho de arquivo (quando o servidor MCP tem acesso ao sistema de arquivos):

attachments: "/path/to/file.pdf, /path/to/doc.xlsx"

Base64 inline (quando o chamador está em um sandbox):

attachments_inline: [{"filename": "report.pdf", "content_base64": "JVBERi0...", "content_type": "application/pdf"}]

Envio de convites de calendário

Passe o conteúdo ICS bruto via calendar_ics. O e-mail é estruturado como multipart/alternative para que os clientes exibam botões Aceitar/Recusar:

calendar_ics: "BEGIN:VCALENDAR\r\nVERSION:2.0\r\n..."

Portão de confirmação de envio

Se send_code estiver definido em accounts.json, a IA deve mostrar o rascunho do e-mail ao usuário e aguardar que ele forneça o código antes de enviar. Isso é útil como um ponto de verificação do fluxo de trabalho para reduzir envios acidentais.

Importante: isso não é uma fronteira de segurança rígida se o processo MCP e o runtime da IA puderem ler a mesma fonte de configuração. Nessa configuração, a IA pode ser capaz de ler o código de accounts.json ou de variáveis de ambiente. Remova ou limpe send_code para desativar o ponto de verificação.

Testes

Execute a suíte de regressão a partir da raiz do repositório:

.venv/bin/python -m unittest discover -s tests -v

Segurança

As senhas são armazenadas em accounts.json — adicione-o ao .gitignore
O portão send_code é um ponto de verificação de intenção do usuário, não um segredo rígido, a menos que a IA não possa ler a fonte de configuração que o contém
Nenhuma senha é exposta pela ação list_accounts
Anexos de arquivo: O parâmetro attachments lê arquivos de caminhos fornecidos pela IA. Se o servidor MCP for executado com amplo acesso ao sistema de arquivos, a IA poderia teoricamente anexar e enviar qualquer arquivo legível. Use attachments_inline (base64) em ambientes de sandbox ou restrinja o acesso ao sistema de arquivos no nível do SO/contêiner.
Salvando anexos: save_attachment falha se o arquivo de destino já existir, a menos que overwrite=true seja definido explicitamente.

Notas do provedor

Gmail

Use uma Senha de aplicativo (não sua senha do Google). Ative o IMAP nas configurações do Gmail.

Outlook / Microsoft 365

Use uma Senha de aplicativo ou ative a autenticação básica para IMAP/SMTP.

Purelymail

Use a senha da sua conta Purelymail diretamente.

Licença

MIT — consulte LICENSE

Autores

Ramon Ramirez (@mexican75)

simple-email-mcp

Documentação

simple-email-mcp

Recursos

Início rápido

1. Instalação

2. Crie accounts.json

3. Adicione ao seu cliente

4. Reinicie seu cliente

Configuração

accounts.json

Campos

Variáveis de ambiente (conta única)

Ferramentas

Validação de configuração

Migrando da v1

Envio com anexos

Envio de convites de calendário

Portão de confirmação de envio

Testes

Segurança

Notas do provedor

Gmail

Outlook / Microsoft 365

Purelymail

Licença

Autores

2. Crie `accounts.json`