Stalwart MCP

mcp-server-stalwart

Servidor MCP para Stalwart Mail Server. Fornece operações de e-mail (pesquisa, leitura, envio, exclusão) via JMAP e acesso opcional à API de administração para gerenciamento do servidor.

Requisitos

• Rust (2024 edition)
• Um servidor de e-mail Stalwart com JMAP habilitado

Compilação

cargo build --release

O binário é gerado em target/release/mcp-server-stalwart.

Configuração

O servidor se conecta via stdio e é configurado por meio de variáveis de ambiente.

Obrigatório

Variável	Descrição
JMAP_SESSION_URL	Endpoint da sessão JMAP (ex.: https://mail.example.com/jmap/session)
JMAP_USERNAME	Endereço de e-mail da conta JMAP
JMAP_PASSWORD	Senha da conta JMAP

Opcional (outras caixas de correio)

Alterne as ferramentas para outra caixa de correio com account (ex.: hello@codechap.com) sem precisar da API de administração.

Variável	Descrição
JMAP_SECRETS_FILE	Caminho para um secrets.toml do mailman4 (tabela [passwords] de "email" = "password")
JMAP_ACCOUNTS	Lista email=password;other@host=password inline (substitui o arquivo em caso de conflito)

Opcional (API de administração)

Variável	Descrição
STALWART_ADMIN_URL	URL base da API de administração — https://mail.example.com ou https://mail.example.com/api (ambos aceitos; /api é normalizado)
STALWART_ADMIN_USER	Nome de usuário do administrador (padrão: admin)
STALWART_ADMIN_PASSWORD	Senha do administrador (principal diferente das senhas de caixa de correio)

Pegadinha de senha (aprendida da pior forma)

Segredo	Usado para	NÃO usado para
JMAP_PASSWORD / senha da caixa de correio	Envio SMTP (smtp://user:pass@host:587), JMAP, IMAP para essa conta	API de administração
STALWART_ADMIN_PASSWORD	API de administração (/api/principal, /api/logs, …)	DSNs de mailer de aplicativos

Se um aplicativo (mailer de fatura, WordPress, etc.) estiver configurado com a senha do administrador como segredo SMTP, o Stalwart retorna 535 Authentication credentials invalid e nada é enfileirado. check_sent mostrará corretamente zero envios. Use verify_account_auth para testar as credenciais antes de perseguir a entrega.

Configuração do MCP do Claude Code

{
  "mcpServers": {
    "stalwart": {
      "command": "/path/to/mcp-server-stalwart",
      "env": {
        "JMAP_SESSION_URL": "https://mail.example.com/jmap/session",
        "JMAP_USERNAME": "you@example.com",
        "JMAP_PASSWORD": "your-password",
        "JMAP_SECRETS_FILE": "/home/you/.local/share/mailman4/secrets.toml",
        "STALWART_ADMIN_URL": "https://mail.example.com",
        "STALWART_ADMIN_PASSWORD": "admin-password"
      }
    }
  }
}

Ferramentas

get_mailboxes

Lista todas as caixas de correio/pastas com contagens de mensagens.

Parâmetro	Tipo	Obrigatório	Descrição
account	string	não	Caixa de correio a listar (ex.: hello@codechap.com)

create_mailbox

Cria uma nova caixa de correio/pasta.

Parâmetro	Tipo	Obrigatório	Descrição
name	string	sim	Nome da caixa de correio
parent_id	string	não	ID da caixa de correio pai para aninhamento (nível superior se omitido)
role	string	não	Função padrão: archive, drafts, inbox, junk, sent, trash

search_emails

Pesquisa e-mails com filtros. Retorna IDs de e-mail -- use get_emails para ler o conteúdo completo.

Parâmetro	Tipo	Obrigatório	Descrição
query	string	não	Texto para pesquisar em assunto, corpo, de, para
from	string	não	Filtrar por endereço do remetente
to	string	não	Filtrar por endereço do destinatário
subject	string	não	Filtrar por texto do assunto
mailbox_id	string	não	Restringir a uma caixa de correio específica
position	number	não	Deslocamento de paginação (padrão 0)
limit	number	não	Máximo de resultados (padrão 10, máx. 50)
account	string	não	Caixa de correio para pesquisar (ex.: hello@codechap.com)

get_emails

Obtém o conteúdo completo do e-mail por IDs. Retorna assunto, de, para, data, texto do corpo e metadados.

Parâmetro	Tipo	Obrigatório	Descrição
ids	string[]	sim	Lista de IDs de e-mail para recuperar
account	string	não	Caixa de correio que possui esses e-mails

delete_emails

Exclui permanentemente e-mails por ID. Não pode ser desfeito.

Parâmetro	Tipo	Obrigatório	Descrição
ids	string[]	sim	Lista de IDs de e-mail para excluir
account	string	não	Caixa de correio da qual excluir

send_email

Envia um e-mail com corpo HTML opcional e anexos de arquivo. Quando html_body é fornecido, o e-mail é enviado como multipart com partes de texto simples e HTML -- o cliente de e-mail do destinatário escolherá qual exibir.

Parâmetro	Tipo	Obrigatório	Descrição
to	string[]	sim	Endereços de e-mail dos destinatários
subject	string	sim	Assunto do e-mail
body	string	sim	Corpo em texto simples
html_body	string	não	Corpo HTML. Quando fornecido, o e-mail é enviado como multipart (text/plain + text/html)
cc	string[]	não	Destinatários em CC
bcc	string[]	não	Destinatários em CCO
attachments	object[]	não	Anexos de arquivo (veja abaixo)
account	string	não	Enviar como esta caixa de correio (ex.: hello@codechap.com) em vez do usuário JMAP padrão

Objeto de anexo:

Campo	Tipo	Obrigatório	Descrição
path	string	sim	Caminho absoluto para o arquivo no disco
filename	string	sim	Nome do arquivo para o anexo
content_type	string	não	Tipo MIME (detectado automaticamente pela extensão se omitido)

download_attachments

Baixa todos os anexos de um e-mail para um diretório local.

Parâmetro	Tipo	Obrigatório	Descrição
email_id	string	sim	ID do e-mail do qual baixar anexos
download_dir	string	sim	Caminho do diretório para salvar os anexos

create_account (admin)

Cria uma nova conta de e-mail no servidor. Requer configuração da API de administração.

Parâmetro	Tipo	Obrigatório	Descrição
email	string	sim	Endereço de e-mail principal
password	string	sim	Senha da conta
description	string	não	Nome de exibição
quota	number	não	Cota de disco em bytes (0 para ilimitado)
permissions	string[]	não	Permissões a conceder na criação (ex.: email-send, authenticate, imap-authenticate). Sem permissões, a conta não pode autenticar ou enviar e-mail — forneça-as aqui ou chame update_account_permissions depois.

list_accounts (admin)

Lista todas as contas ou obtém detalhes de uma. Requer configuração da API de administração.

Parâmetro	Tipo	Obrigatório	Descrição
name	string	não	Nome da conta para detalhes. Se omitido, lista todas as contas.

manage_aliases (admin)

Adiciona ou remove um alias de e-mail em uma conta. Requer configuração da API de administração.

Parâmetro	Tipo	Obrigatório	Descrição
account	string	sim	Nome da conta
action	string	sim	add ou remove
alias	string	sim	E-mail de alias para adicionar/remover

update_account_permissions (admin)

Atualiza o enabledPermissions de uma conta. Principals recém-criados começam sem permissões e não podem autenticar, enviar ou receber e-mail até que as permissões sejam concedidas. Requer configuração da API de administração.

Parâmetro	Tipo	Obrigatório	Descrição
account	string	sim	Nome da conta de destino
action	string	não	set (substituir lista, padrão), add (conceder) ou remove (revogar)
permissions	string[]	sim	Nomes de permissões (ex.: email-send, authenticate, imap-authenticate, imap-append)

reset_password (admin)

Redefine a senha de uma conta. Se password for omitido, uma senha aleatória forte de 24 caracteres é gerada. A nova senha é retornada em texto simples na resposta para que possa ser entregue ao usuário. Requer configuração da API de administração.

Parâmetro	Tipo	Obrigatório	Descrição
account	string	sim	Nome da conta de destino
password	string	não	Nova senha. Gerada automaticamente se omitida.

get_dsn_accounts (admin)

Lista endereços de e-mail que têm relatórios de entrega DSN (Notificação de Status de Entrega) habilitados. Requer configuração da API de administração.

set_dsn_accounts (admin)

Define quais endereços de e-mail recebem relatórios de entrega DSN (SUCCESS + FAILURE). Substitui a lista completa. Requer configuração da API de administração.

Parâmetro	Tipo	Obrigatório	Descrição
accounts	string[]	sim	Endereços de e-mail para habilitar relatórios de entrega

check_sent (admin)

A primeira ferramenta a usar ao verificar qualquer e-mail de saída — formulários de contato, WordPress wp_mail(), mailers de fatura/extrato, redefinições de senha, e-mail transacional — qualquer coisa que precise de "isso saiu do servidor?".

Lê o /api/logs do Stalwart (autoritativo) e agrupa por queueId: envio → tentativa de entrega → status final (delivery.delivered / delivery.dsn-success / delivery.failed) mais MX upstream code/hostname.

NÃO pesquise caixas de correio primeiro — envios SMTP não são salvos automaticamente em Enviados. Comece aqui.

Como funciona a busca de log (lição de produção):
A consulta filter= do lado do servidor do Stalwart frequentemente trava em arquivos de log diários de vários GB. Por padrão, esta ferramenta busca as linhas scan_limit mais recentes sem filtro e aplica to/from/filter no lado do cliente (rápido: ~300ms para 1000 linhas). Passe use_server_filter=true somente se você souber que precisa (ex.: um queueId único em um host tranquilo).

Casos de uso comuns:

• "O mailer de fatura / formulário de contato enviou para ap@client.com?"
• "Um e-mail transacional foi entregue — o que o Gmail retornou?"
• "Por que rejeição — código SMTP remoto?"

Parâmetro	Tipo	Obrigatório	Descrição
to	string	não	E-mail ou domínio do destinatário (substring no lado do cliente). Prefira isso para verificações de formulário de contato.
from	string	não	E-mail ou domínio do remetente (substring no lado do cliente).
filter	string	não	Substring extra no lado do cliente (ex.: queueId).
since	string	não	Limite inferior RFC3339 nos carimbos de data/hora dos eventos.
scan_limit	number	não	Linhas de log mais recentes a buscar (padrão 500, máx. 5000). Aumente se o envio for mais antigo que a janela.
use_server_filter	bool	não	Padrão false. Se true, passe o filtro para o Stalwart (pode expirar em hosts ocupados).

Retorna messages_found, delivered_count, failed_count, linhas do tempo por mensagem (mx_code / mx_hostname), além de auth_events (sucesso/falha de autenticação de envio) e um log_window.

verify_account_auth

Testa se um nome de usuário/senha é aceito pelo Stalwart (mesmo segredo da porta SMTP 587). Use quando check_sent mostrar nenhum envio — geralmente o aplicativo tem a senha errada.

Parâmetro	Tipo	Obrigatório	Descrição
username	string	sim	E-mail da conta (ex.: hello@codechap.com)
password	string	sim	Senha candidata (segredo da caixa de correio, não do administrador)