Mailtrap MCP Server

oficial

Integra-se com Mailtrap Email API.

GitHub
60

Documentação

TypeScript test NPM

Servidor MCP Mailtrap

Um servidor MCP que fornece ferramentas para envio e teste em sandbox via Mailtrap.

Pré-requisitos

Antes de usar este servidor MCP, você precisa:

  1. Criar uma conta no Mailtrap
  2. Verificar seu domínio
  3. Obter seu token de API nas configurações de API do Mailtrap
  4. Obter seu ID de Conta no gerenciamento de conta do Mailtrap

Variáveis de Ambiente Obrigatórias:

  • MAILTRAP_API_TOKEN - Obrigatória para todas as funcionalidades
  • MAILTRAP_ACCOUNT_ID - Obrigatória para templates, estatísticas, logs de email, listagem/exibição de sandbox e domínios de envio. Opcional apenas para send-email e send-sandbox-email.

Opcionais (podem ser passadas como parâmetros da ferramenta):

  • DEFAULT_FROM_EMAIL - Remetente padrão quando from não é fornecido para send-email ou send-sandbox-email. Permite alternar o remetente por chamada via parâmetro from.
  • MAILTRAP_TEST_INBOX_ID - ID da caixa de entrada de teste padrão para ferramentas sandbox quando test_inbox_id não é fornecido. Permite alternar entre caixas de entrada por chamada via parâmetro test_inbox_id.
  • MAILTRAP_SANDBOX_ID - ID do sandbox padrão para ferramentas sandbox quando sandbox_id não é fornecido. Permite alternar entre sandboxes por chamada via parâmetro sandbox_id.
  • MAILTRAP_ORGANIZATION_ID - Obrigatória para ferramentas de organização (list-sub-accounts, create-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN - Token de API com escopo de organização. Obrigatório para ferramentas de organização (separado de MAILTRAP_API_TOKEN).

Instalação Rápida

Install in Cursor

Install with Node in VS Code

Smithery CLI

Smithery é um instalador e gerenciador de registro para servidores MCP que funciona com todos os clientes de IA.

npx @smithery/cli install mailtrap

O Smithery gerencia automaticamente a configuração do cliente e oferece um processo de configuração interativo. É a maneira mais fácil de começar com servidores MCP localmente.

Configuração

Claude Desktop

Use o MCPB para instalar o servidor Mailtrap. Você pode encontrar esses arquivos em Releases.
Baixe o arquivo .MCPB e abra-o. Se você tiver o Claude Desktop - ele abrirá e sugerirá a configuração.

Claude Desktop ou Cursor

Adicione a seguinte configuração:

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Se você estiver usando asdf para gerenciar o Node.js, deve usar o caminho absoluto para o executável (exemplo para Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Localização do arquivo de configuração do Claude Desktop

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Localização do arquivo de configuração do Cursor

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

Alterando a configuração manualmente

Execute na Paleta de Comandos: Preferences: Open User Settings (JSON)

Em seguida, no arquivo de configurações, adicione a seguinte configuração:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] Não se esqueça de reiniciar seu servidor MCP após alterar a seção "env".

MCP Bundle (MCPB)

Para fácil instalação em hosts que suportam MCP Bundles, você pode distribuir um arquivo de bundle .mcpb.

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

Isso cria mailtrap-mcp.mcpb usando o repositório manifest.json e artefatos compilados em dist/.

Uso

Uma vez configurado, você pode pedir ao agente para enviar emails e gerenciar templates, por exemplo:

Operações de Envio de Email:

  • "Envie um email para [email protected] com o assunto 'Reunião Amanhã' e um lembrete amigável sobre nossa próxima reunião."
  • "Envie um email para [email protected] sobre a atualização do projeto, com cópia para a equipe em [email protected]"
  • "Envie o template de boas-vindas (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) para [email protected] com as variáveis { name: 'Alex' }"
  • "Envie um email sandbox para [email protected] com assunto 'Template de Teste' para visualizar como nosso email de boas-vindas fica"

Logs de Email (depuração de entrega):

  • "Liste meus logs recentes de emails enviados"
  • "Mostre os logs de email para emails enviados para [email protected]"
  • "Obtenha a mensagem do log de email para o ID abc-123-uuid para verificar o status de entrega"

Estatísticas de Envio:

  • "Obtenha estatísticas de envio para janeiro de 2025"
  • "Mostre as taxas de entrega discriminadas por domínio no último mês"
  • "Quais são minhas estatísticas de email por categoria de 2025-01-01 a 2025-01-31?"

Operações Sandbox:

  • "Obtenha todas as mensagens da minha caixa de entrada sandbox"
  • "Mostre a primeira página de mensagens sandbox"
  • "Pesquise mensagens contendo 'teste' na minha caixa de entrada sandbox"
  • "Mostre os detalhes da mensagem sandbox com ID 5159037506"

Operações com Templates:

  • "Liste todos os templates de email na minha conta Mailtrap"
  • "Crie um novo template de email chamado 'Email de Boas-vindas' com assunto 'Bem-vindo à nossa plataforma!'"
  • "Atualize o template com ID 12345 para alterar o assunto para 'Mensagem de Boas-vindas Atualizada'"
  • "Exclua o template com ID 67890"

Domínios de Envio:

  • "Liste meus domínios de envio"
  • "Obtenha o domínio de envio com ID 3938"
  • "Crie um domínio de envio para example.com"
  • "Exclua o domínio de envio 3938"
  • "Obtenha o domínio de envio 3938 com instruções de configuração de DNS"

Ferramentas Disponíveis

send-email

Envia um email transacional através do Mailtrap. Suporta dois modos mutuamente exclusivos — conteúdo inline (subject + text/html) ou baseado em template (template_uuid).

Parâmetros:

  • from (opcional): Remetente como uma string de email ou { email, name? }. Se não fornecido, DEFAULT_FROM_EMAIL é usado.
  • to (opcional): Destinatário(s) — um único email/{ email, name? } ou um array. Opcional se cc ou bcc for fornecido; pelo menos um de to / cc / bcc deve conter um destinatário.
  • cc (opcional): Array de destinatários em CC (strings de email ou { email, name? } cada).
  • bcc (opcional): Array de destinatários em BCC (strings de email ou { email, name? } cada).
  • subject (condicional): Linha de assunto do email. Obrigatório para envios inline; deve ser omitido quando template_uuid estiver definido.
  • text (condicional): Corpo do email em texto. Obrigatório (junto ou em vez de html) para envios inline; deve ser omitido quando template_uuid estiver definido.
  • html (condicional): Versão HTML do corpo do email. Obrigatório (junto ou em vez de text) para envios inline; deve ser omitido quando template_uuid estiver definido.
  • category (opcional): Categoria do email para rastreamento e análise. Deve ser omitido quando template_uuid estiver definido.
  • template_uuid (opcional): Use um template de email do Mailtrap em vez de conteúdo inline. Quando definido, subject / text / html / category devem ser omitidos (conforme API do Mailtrap).
  • template_variables (opcional): Objeto de variáveis substituídas no template referenciado por template_uuid. Permitido apenas junto com template_uuid.

batch-send-transactional-email

Envia um lote de emails transacionais em uma chamada de API do Mailtrap (fluxo de envio padrão). Campos compartilhados vão em base; substituições por destinatário vão em requests[]. Cada requisição deve incluir pelo menos um destinatário via to, cc ou bcc. Mesma exclusão mútua inline-vs-template que send-email — verificada após mesclar a base com cada requisição.

Parâmetros:

  • base (opcional): Objeto com campos compartilhados no lote.
    • from (opcional): Remetente como uma string de email ou { email, name? }. Recai para DEFAULT_FROM_EMAIL.
    • reply_to (opcional): Endereço de resposta (reply-to).
    • subject / text / html / category (opcional, modo inline): Conteúdo padrão para cada requisição.
    • template_uuid / template_variables (opcional, modo template): Template padrão + variáveis. Mutuamente exclusivo com os campos inline.
    • custom_variables (opcional): Variáveis personalizadas padrão (com valor string).
    • headers (opcional): Cabeçalhos personalizados padrão.
  • requests (obrigatório): Array não vazio de mensagens por destinatário. Cada entrada possui:
    • to (opcional): Destinatário(s) — string, { email, name? } ou um array. Opcional se cc ou bcc for fornecido; pelo menos um de to / cc / bcc deve conter um destinatário.
    • cc, bcc, reply_to (opcional).
    • Substituições inline (subject/text/html/category) ou template (template_uuid/template_variables); qualquer campo omitido recai para o valor correspondente em base.
    • custom_variables, headers (opcional).

batch-send-bulk-email

Envia um lote de emails em massa através da API de fluxo em massa do Mailtrap. Mesmo formato de base + requests[], validação e regras inline-vs-template que batch-send-transactional-email — a única diferença é que esta ferramenta roteia a chamada através do endpoint em massa em vez do transacional. Veja os parâmetros acima.

list-email-logs

Lista logs de emails enviados (histórico de entrega) com paginação e filtros opcionais. Use para depurar problemas de entrega do IDE.

Parâmetros:

  • search_after (opcional): Cursor de paginação do next_page_cursor da resposta anterior
  • sent_after (opcional): Data/hora ISO 8601; apenas logs enviados após este horário
  • sent_before (opcional): Data/hora ISO 8601; apenas logs enviados antes deste horário
  • from_email (opcional): Filtrar por email do remetente; use com from_operator (padrão: ci_equal)
  • to_email (opcional): Filtrar por email do destinatário; use com to_operator (padrão: ci_equal)
  • status (opcional): Filtrar por status de entrega: delivered, not_delivered, enqueued, opted_out; use com status_operator (padrão: equal)
  • subject (opcional): Filtrar por assunto do email; use com subject_operator (padrão: ci_contain). Use subject_operator: empty/not_empty para filtrar pela presença de assunto.
  • sending_domain_id (opcional): Filtrar por ID do domínio de envio (número); use com sending_domain_id_operator (padrão: equal)
  • sending_stream (opcional): Filtrar por fluxo: transactional ou bulk; use com sending_stream_operator (padrão: equal)
  • events (opcional): Filtrar por tipo(s) de evento: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; use com events_operator (include_event / not_include_event)
  • clicks_count / opens_count (opcional): Filtrar por contagem de cliques/aberturas; use com *_operator: equal, greater_than, less_than
  • client_ip / sending_ip (opcional): Filtrar por IP; use com *_operator: equal, not_equal, contain, not_contain
  • email_service_provider_response (opcional): Filtrar por texto de resposta do provedor; use com *_operator (ci_contain, etc.)
  • email_service_provider (opcional): Filtrar por provedor (exato); use com *_operator: equal, not_equal
  • recipient_mx (opcional): Filtrar por MX do destinatário; use com recipient_mx_operator (ci_contain, etc.)
  • category (opcional): Filtrar por categoria de email; use com category_operator: equal, not_equal

Todos os parâmetros são opcionais.

get-email-log-message

Obtém uma única mensagem de log de email por ID (UUID): um resumo legível (de, para, assunto, horário de envio, status, categoria, fluxo, engajamento, contexto de entrega) e, em seguida, histórico detalhado de eventos. Opcionalmente, com include_content: true, você também pode carregar e mostrar o corpo da mensagem (HTML e texto simples) quando o Mailtrap expõe uma URL de mensagem bruta.

Parâmetros:

  • message_id (obrigatório): UUID da mensagem de log de email (da resposta de envio ou list-email-logs). Use list-email-logs para encontrar IDs de mensagens.
  • include_content (opcional): Quando true, busca o EML bruto (se raw_message_url estiver disponível) e anexa seções de corpo HTML e texto simples analisadas, semelhante a show-sandbox-email-message.

get-sending-stats

Obtenha estatísticas de envio de email (taxas de entrega, bounce, abertura, clique, spam) para um intervalo de datas. Opcionalmente, discrimine por domínio, categoria, provedor de serviço de email ou data. Verifique as taxas de entrega sem sair do editor.

Parâmetros:

  • start_date (obrigatório): Data de início do intervalo de estatísticas (AAAA-MM-DD)
  • end_date (obrigatório): Data de término do intervalo de estatísticas (AAAA-MM-DD)
  • breakdown (opcional): Como detalhar as estatísticas: aggregated (padrão), by_domain, by_category, by_email_service_provider ou by_date
  • sending_domain_ids (opcional): Limitar resultados a estes IDs de domínio de envio (array de inteiros)
  • sending_streams (opcional): Limitar a transactional e/ou bulk (array de strings)
  • categories (opcional): Limitar a estas categorias de e-mail (array de strings)
  • email_service_providers (opcional): Limitar a estes provedores, ex.: Google, Yahoo, Outlook (array de strings)

create-template

Cria um novo modelo de e-mail na sua conta do Mailtrap.

Parâmetros:

  • name (obrigatório): Nome do modelo
  • subject (obrigatório): Linha de assunto do e-mail
  • html (ou text é obrigatório): Conteúdo HTML do modelo
  • text (ou html é obrigatório): Versão em texto simples do modelo
  • category (opcional): Categoria do modelo (padrão: "General")

list-templates

Lista todos os modelos de e-mail na sua conta do Mailtrap.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-template

Obtém um único modelo de e-mail pelo ID, incluindo assunto, categoria e corpo HTML/texto.

Parâmetros:

  • template_id (obrigatório): ID do modelo a ser buscado

update-template

Atualiza um modelo de e-mail existente.

Parâmetros:

  • template_id (obrigatório): ID do modelo a ser atualizado
  • name (opcional): Novo nome para o modelo
  • subject (opcional): Nova linha de assunto do e-mail
  • html (opcional): Novo conteúdo HTML do modelo
  • text (opcional): Nova versão em texto simples do modelo
  • category (opcional): Nova categoria para o modelo

[!NOTE] Pelo menos um campo atualizável (nome, assunto, html, texto ou categoria) deve ser fornecido ao chamar update-template para realizar uma atualização.

delete-template

Exclui um modelo de e-mail existente.

Parâmetros:

  • template_id (obrigatório): ID do modelo a ser excluído

send-sandbox-email

Envia um e-mail para sua caixa de entrada de teste do Mailtrap para fins de desenvolvimento e teste. Isso é perfeito para testar modelos de e-mail sem enviar e-mails para destinatários reais. Suporta os mesmos dois modos que send-email — conteúdo inline ou baseado em modelo (template_uuid).

Parâmetros:

  • test_inbox_id (opcional): ID da caixa de entrada de teste do Mailtrap. Obrigatório a menos que MAILTRAP_TEST_INBOX_ID esteja definido; passe por chamada para direcionar uma caixa de entrada específica.
  • from (opcional): Remetente como uma string de e-mail ou { email, name? }. Se não fornecido, DEFAULT_FROM_EMAIL é usado.
  • to (opcional): Destinatários como uma string separada por vírgulas, ou um array de strings de e-mail / objetos { email, name? }. Opcional se cc ou bcc for fornecido; pelo menos um de to / cc / bcc deve conter um destinatário.
  • cc (opcional): Array de destinatários CC (strings de e-mail ou { email, name? } cada).
  • bcc (opcional): Array de destinatários BCC (strings de e-mail ou { email, name? } cada).
  • subject (condicional): Linha de assunto do e-mail. Obrigatório para envios inline; deve ser omitido quando template_uuid estiver definido.
  • text (condicional): Corpo do e-mail em texto. Obrigatório (junto ou em vez de html) para envios inline; deve ser omitido quando template_uuid estiver definido.
  • html (condicional): Versão HTML do corpo do e-mail. Obrigatório (junto ou em vez de text) para envios inline; deve ser omitido quando template_uuid estiver definido.
  • category (opcional): Categoria do e-mail para rastreamento. Deve ser omitido quando template_uuid estiver definido.
  • template_uuid (opcional): Usar um modelo de e-mail do Mailtrap em vez de conteúdo inline. Quando definido, subject / text / html / category devem ser omitidos.
  • template_variables (opcional): Objeto de variáveis substituídas no modelo referenciado por template_uuid. Permitido apenas junto com template_uuid.

[!NOTE] Para ferramentas sandbox, forneça test_inbox_id na chamada da ferramenta ou defina a variável de ambiente MAILTRAP_TEST_INBOX_ID. Você pode alternar entre caixas de entrada por chamada passando test_inbox_id.

get-sandbox-messages

Recupera uma lista de mensagens da sua caixa de entrada de teste do Mailtrap. Útil para verificar quais e-mails foram recebidos no seu sandbox durante os testes.

Parâmetros:

  • page (opcional): Número da página para paginação (mínimo: 1)
  • last_id (opcional): Paginação usando o ID da última mensagem. Retorna mensagens após o ID de mensagem especificado (mínimo: 1)
  • search (opcional): Consulta de pesquisa para filtrar mensagens

[!NOTE] Todos os parâmetros são opcionais. Se nenhum for fornecido, a primeira página de mensagens da caixa de entrada será retornada. Use page para paginação tradicional, last_id para paginação baseada em cursor, ou search para filtrar mensagens por conteúdo.

show-sandbox-email-message

Mostra informações detalhadas e conteúdo de uma mensagem de e-mail específica da sua caixa de entrada de teste do Mailtrap, incluindo conteúdo do corpo HTML e texto.

Parâmetros:

  • message_id (obrigatório): ID da mensagem de e-mail do sandbox a ser recuperada

[!NOTE] Use get-sandbox-messages primeiro para obter a lista de mensagens e seus IDs, depois use esta ferramenta para visualizar o conteúdo completo de uma mensagem específica.

get-sandbox-project

Obtém um projeto sandbox pelo ID, incluindo suas caixas de entrada e contagens de e-mails.

Parâmetros:

  • project_id (obrigatório): ID do projeto a ser buscado

update-sandbox-project

Renomeia um projeto sandbox existente.

Parâmetros:

  • project_id (obrigatório): ID do projeto a ser atualizado
  • name (obrigatório): Novo nome para o projeto (2–100 caracteres)

list-sandboxes

Lista todos os sandboxes acessíveis ao token da API em todos os projetos.

Parâmetros:

  • Nenhum parâmetro obrigatório

mark-sandbox-as-read

Marca todas as mensagens em um sandbox como lidas.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox a ser afetado

reset-sandbox-credentials

Redefine as credenciais SMTP de um sandbox. Retorna o novo nome de usuário/senha.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox a ser afetado

enable-sandbox-email-address

Ativa o endereço de recebimento por e-mail para um sandbox (ativa o endereço do Mailtrap que entrega mensagens ao sandbox via SMTP).

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox a ser afetado

reset-sandbox-email-address

Gera um novo endereço de recebimento por e-mail para um sandbox.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox a ser afetado

forward-sandbox-message

Encaminha uma mensagem do sandbox para um endereço de e-mail externo. Conta contra sua cota mensal de encaminhamento.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox a ser encaminhada
  • email (obrigatório): Endereço de e-mail para o qual encaminhar a mensagem

update-sandbox-message

Marca uma mensagem do sandbox como lida ou não lida.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox a ser atualizada
  • is_read (obrigatório): true marca como lida, false marca como não lida

delete-sandbox-message

Exclui uma única mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox a ser excluída

get-sandbox-message-spam-score

Obtém o relatório de spam do SpamAssassin para uma mensagem do sandbox (pontuação, regras, relatório completo). Alternativa independente a include_spam_report: true em show-sandbox-email-message.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-html-analysis

Obtém o relatório de análise HTML para uma mensagem do sandbox (pontuações de compatibilidade com clientes, elementos problemáticos). Alternativa independente a include_html_analysis: true em show-sandbox-email-message.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-headers

Obtém os cabeçalhos de e-mail analisados para uma mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-html

Obtém o corpo HTML renderizado de uma mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-text

Obtém o corpo em texto simples de uma mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-raw

Obtém a mensagem bruta, formatada em MIME (cabeçalhos + corpo) para uma mensagem do sandbox.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-eml

Obtém a mensagem renderizada como um payload de arquivo EML (adequado para anexar a um ticket ou importar para outro cliente de e-mail).

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-message-html-source

Obtém o código-fonte HTML não renderizado de uma mensagem do sandbox (HTML antes de quaisquer transformações do lado do Mailtrap, como reescritas de links CID).

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

list-sandbox-attachments

Lista todos os anexos em uma mensagem do sandbox (nome do arquivo, tipo de conteúdo, tamanho, caminho de download).

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox

get-sandbox-attachment

Obtém metadados e URL de download para um único anexo.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox. Recorre a MAILTRAP_SANDBOX_ID.
  • message_id (obrigatório): ID da mensagem do sandbox que contém o anexo
  • attachment_id (obrigatório): ID do anexo a ser buscado

list-sending-domains

Lista domínios de envio e seu status de verificação DNS.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-sending-domain

Obtém um domínio de envio pelo ID e seu status de verificação (incluindo registros DNS). Opcionalmente, inclui instruções de configuração DNS definindo include_setup_instructions como true.

Parâmetros:

  • sending_domain_id (obrigatório): ID do domínio de envio
  • include_setup_instructions (opcional): Se true, anexa instruções de configuração DNS à resposta. Padrão: false

create-sending-domain

Cria um novo domínio de envio. Após a criação, adicione registros DNS para verificar o domínio (use get-sending-domain com include_setup_instructions: true para ver os registros).

Parâmetros:

  • domain_name (obrigatório): Nome do domínio (ex.: exemplo.com)

delete-sending-domain

Exclui um domínio de envio.

Parâmetros:

  • sending_domain_id (obrigatório): ID do domínio de envio a ser excluído

send-sending-domain-setup-instructions

Envia instruções de configuração DNS para um domínio de envio por e-mail para um endereço fornecido. Útil para encaminhar registros DNS para um colega de DevOps.

Parâmetros:

  • sending_domain_id (obrigatório): ID do domínio de envio
  • email (obrigatório): Endereço de e-mail para o qual enviar as instruções de configuração DNS

list-suppressions

Lista ou pesquisa supressões (hard bounces, reclamações de spam, cancelamentos de inscrição, importações manuais). Retorna até 1000 resultados por chamada.

Parâmetros:

  • email (opcional): Filtro de e-mail. Retorna apenas supressões que correspondam a este endereço.

delete-suppression

Exclui uma supressão pelo ID. O Mailtrap retomará a entrega para este e-mail, a menos que ele seja suprimido novamente.

Parâmetros:

  • suppression_id (obrigatório): ID da supressão a ser excluída

list-webhooks

Lista todos os webhooks configurados para a conta. Retorna os registros completos dos webhooks como JSON.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-webhook

Obtém um único webhook pelo ID. Retorna o registro completo do webhook como JSON. Nota: signing_secret não é retornado aqui — ele está disponível apenas na resposta de create-webhook.

Parâmetros:

  • webhook_id (obrigatório): ID do webhook a ser buscado

create-webhook

Cria um webhook. A resposta inclui um signing_secret para verificar assinaturas de payload do webhook — este segredo é retornado apenas na criação, portanto armazene-o agora. Se você perdê-lo, recrie o webhook.

Parâmetros:

  • url (obrigatório): URL para a qual o Mailtrap enviará eventos do webhook via POST
  • webhook_type (obrigatório): "email_sending" ou "audit_log"
  • active (opcional, booleano): o padrão é true
  • payload_format (opcional): "json" ou "jsonlines". O padrão é "json"
  • sending_stream (opcional, somente email_sending): "transactional" ou "bulk"
  • event_types (opcional, somente email_sending): array de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (opcional, somente email_sending): ID do domínio de envio para limitar o escopo deste webhook

update-webhook

Atualiza os campos mutáveis de um webhook. webhook_type, sending_stream e domain_id não podem ser alterados após a criação — recrie o webhook se precisar alterá-los.

Parâmetros:

  • webhook_id (obrigatório): ID do webhook a ser atualizado
  • url (opcional): Nova URL do webhook
  • active (opcional, booleano): Habilita ou desabilita o webhook
  • payload_format (opcional): "json" ou "jsonlines"
  • event_types (opcional, somente email_sending): array de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject

delete-webhook

Exclui permanentemente um webhook pelo ID. Retorna o registro do webhook excluído.

Parâmetros:

  • webhook_id (obrigatório): ID do webhook a ser excluído

get-contact

Obtém um contato por ID ou e-mail. Retorna o registro completo do contato (associações a listas, status, campos personalizados).

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou endereço de e-mail

create-contact

Cria um novo contato.

Parâmetros:

  • email (obrigatório): Endereço de e-mail
  • fields (opcional): Valores de campos personalizados indexados por tag de mesclagem (ex.: first_name). Valores do tipo string, number ou boolean
  • list_ids (opcional): IDs das listas de contatos nas quais inscrever este contato
  • unsubscribed (opcional, booleano): Cria o contato com o status unsubscribed

update-contact

Atualiza um contato existente identificado por ID ou e-mail. list_ids substitui o conjunto completo de associações do contato; list_ids_included/list_ids_excluded adicionam/removem sem alterar o restante.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou e-mail
  • email (opcional): Novo endereço de e-mail
  • fields (opcional): Valores de campos personalizados indexados por tag de mesclagem
  • list_ids (opcional): Substitui o conjunto de associações por esta lista exata
  • list_ids_included (opcional): IDs de listas a adicionar (aditivo)
  • list_ids_excluded (opcional): IDs de listas a remover
  • unsubscribed (opcional, booleano): Define como unsubscribed (true) ou subscribed (false)

delete-contact

Exclui permanentemente um contato por ID ou e-mail. Retorna o registro do contato excluído quando a API responde com um; caso contrário, retorna um payload de confirmação.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou e-mail

create-contact-event

Registra um evento de contato para um contato (por ID ou e-mail). Usado para acionar automações de lista de contatos.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou e-mail
  • name (obrigatório): Nome do evento (corresponde aos gatilhos de automação)
  • params (obrigatório): Objeto de pares chave/valor arbitrários. Os valores podem ser string, number, boolean ou null

list-contact-lists

Lista todas as listas de contatos da conta.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-contact-list

Obtém uma lista de contatos pelo ID.

Parâmetros:

  • list_id (obrigatório): ID da lista de contatos a ser buscada

create-contact-list

Cria uma nova lista de contatos.

Parâmetros:

  • name (obrigatório): Nome para a nova lista

update-contact-list

Renomeia uma lista de contatos existente.

Parâmetros:

  • list_id (obrigatório): ID da lista de contatos
  • name (obrigatório): Novo nome para a lista

delete-contact-list

Exclui permanentemente uma lista de contatos pelo ID.

Parâmetros:

  • list_id (obrigatório): ID da lista de contatos a ser excluída

list-contact-fields

Lista todas as definições de campos de contato da conta.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-contact-field

Obtém uma definição de campo de contato pelo ID.

Parâmetros:

  • field_id (obrigatório): ID do campo de contato

create-contact-field

Cria uma nova definição de campo de contato. merge_tag deve ser único dentro da conta e é usado como o nome do placeholder em variáveis de template.

Parâmetros:

  • name (obrigatório): Nome de exibição (ex.: "Nome")
  • merge_tag (obrigatório): Nome de placeholder único (ex.: first_name)
  • data_type (obrigatório): Um de text, number, boolean, date

update-contact-field

Atualiza uma definição de campo de contato. Qualquer combinação de name, merge_tag e data_type pode ser alterada.

Parâmetros:

  • field_id (obrigatório): ID do campo de contato
  • name (opcional): Novo nome de exibição
  • merge_tag (opcional): Nova tag de mesclagem (deve permanecer única)
  • data_type (opcional): Um de text, number, boolean, date

delete-contact-field

Exclui permanentemente uma definição de campo de contato pelo ID.

Parâmetros:

  • field_id (obrigatório): ID do campo de contato a ser excluído

create-contact-import

Importa contatos em massa. Retorna um registro de tarefa de importação; consulte seu status com get-contact-import.

Parâmetros:

  • contacts (obrigatório): Array de entradas de contato. Cada entrada precisa de:
    • email (obrigatório): Endereço de e-mail do contato
    • fields (opcional): Valores de campos personalizados indexados por tag de mesclagem (valores string ou number)
    • list_ids_included (opcional): IDs de listas às quais adicionar o contato
    • list_ids_excluded (opcional): IDs de listas das quais remover o contato

get-contact-import

Obtém o status de uma tarefa de importação de contatos (criada/iniciada/finalizada/com falha) com contagens de criados/atualizados/acima do limite.

Parâmetros:

  • import_id (obrigatório): ID da tarefa de importação de contatos

create-contact-export

Exporta contatos que correspondem a um conjunto de filtros combinados com AND. Retorna um registro de tarefa de exportação; consulte o status com get-contact-export para recuperar a URL de download quando status for finished.

Parâmetros:

  • filters (obrigatório): Array de objetos de filtro. Cada um tem:
    • name (obrigatório): Campo para filtrar (list_id, subscription_status, email, etc.)
    • operator (obrigatório): Um de equal, not_equal, contains, not_contains, is_empty, is_not_empty
    • value (obrigatório): Valor de comparação (string, number, boolean ou array)

get-contact-export

Obtém o status de uma tarefa de exportação de contatos. Quando status for finished, o campo url conterá o link de download do CSV.

Parâmetros:

  • export_id (obrigatório): ID da tarefa de exportação de contatos

list-accounts

Lista as contas do Mailtrap que o token de API atual pode acessar, com os níveis de acesso de cada conta.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-billing-usage

Obtém o uso do ciclo de faturamento atual para a conta: planos de envio e teste, limites e contagens atuais.

Parâmetros:

  • Nenhum parâmetro obrigatório

list-account-accesses

Lista os acessos à conta (usuários, convites, tokens de API) para a conta. Filtros opcionais restringem o resultado a recursos específicos. Requer permissões de administrador/proprietário da conta.

Parâmetros:

  • domain_uuids (opcional): Filtrar por UUIDs de domínio de envio (array de strings)
  • inbox_ids (opcional): Filtrar por IDs de caixa de entrada sandbox (array de strings)
  • project_ids (opcional): Filtrar por IDs de projeto sandbox (array de strings)

remove-account-access

Remove um acesso à conta pelo ID. Para especificadores User, isso revoga suas permissões; para especificadores Invite ou ApiToken, remove o especificador completamente. Requer administrador/proprietário.

Parâmetros:

  • account_access_id (obrigatório): ID do registro de acesso a ser removido

get-permission-resources

Obtém todos os recursos (caixas de entrada, projetos, domínios, faturamento, conta) para os quais o token de API tem acesso de administrador, aninhados por hierarquia.

Parâmetros:

  • Nenhum parâmetro obrigatório

bulk-update-permissions

Cria, atualiza ou destrói permissões em massa para um único acesso à conta. Pares (resource_type, resource_id) existentes são atualizados; novos são criados. Defina destroy: true em uma entrada para removê-la.

Parâmetros:

  • account_access_id (obrigatório): ID do acesso à conta de destino
  • permissions (obrigatório): Array de entradas de permissão. Cada uma tem:
    • resource_id (obrigatório): ID do recurso (number ou string)
    • resource_type (obrigatório): Um de account, project, inbox, domain, billing
    • access_level (opcional): admin/100 ou viewer/10
    • destroy (opcional, booleano): Quando true, remove esta permissão em vez de criá-la ou atualizá-la

list-api-tokens

Lista todos os tokens de API da conta.

Parâmetros:

  • Nenhum parâmetro obrigatório

create-api-token

Cria um novo token de API. A resposta inclui o valor secreto token — esta é a única vez que o token completo é retornado, portanto armazene-o imediatamente. Se você perdê-lo, recrie o token.

Parâmetros:

  • name (obrigatório): Nome de exibição para o token
  • resources (opcional): Array de permissões de recursos para limitar o escopo do token. Cada entrada tem:
    • resource_type (obrigatório): Um de account, project, inbox, domain, billing
    • resource_id (obrigatório): ID do recurso
    • access_level (obrigatório): 100 (admin) ou 10 (viewer)

get-api-token

Obtém um token de API pelo ID. Retorna apenas metadados — o valor secreto do token não é retornado aqui (apenas de create-api-token / reset-api-token).

Parâmetros:

  • api_token_id (obrigatório): ID do token de API

reset-api-token

Redefine (rotaciona) um token de API pelo ID. A resposta inclui o novo valor secreto token — retornado apenas nesta chamada, portanto armazene-o imediatamente. O token anterior é invalidado.

Parâmetros:

  • api_token_id (obrigatório): ID do token de API a ser redefinido

delete-api-token

Exclui permanentemente um token de API pelo ID. O token não poderá mais autenticar após a exclusão.

Parâmetros:

  • api_token_id (obrigatório): ID do token de API a ser excluído

list-sub-accounts

Lista as subcontas na organização. Requer a variável de ambiente MAILTRAP_ORGANIZATION_ID e permissões de gerenciamento de subcontas.

Parâmetros:

  • Nenhum parâmetro obrigatório

create-sub-account

Cria uma nova subconta na organização. Requer a variável de ambiente MAILTRAP_ORGANIZATION_ID e permissões de gerenciamento de subcontas.

Parâmetros:

  • name (obrigatório): Nome de exibição para a nova subconta

Desenvolvimento

  1. Clone o repositório:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. Instale as dependências:
npm install

Configuração com Claude Desktop ou Cursor

[!TIP] Veja a localização do arquivo de configuração na seção Configuração.

Adicione a seguinte configuração:

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Se você estiver usando asdf para gerenciar o Node.js, deve usar o caminho absoluto para o executável:

(exemplo para Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] Veja a localização do arquivo de configuração na seção Configuração.

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Testes

Executando ferramentas contra o Mailtrap real

Há duas maneiras de exercitar uma ferramenta de ponta a ponta contra uma conta real do Mailtrap: a interface do navegador do MCP Inspector para exploração interativa, ou seu modo CLI para chamadas pontuais a partir do shell.

Ambos exigem que o pacote seja compilado primeiro:

npm run build

e que MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID estejam exportados no seu shell (o script mcp:cli encaminha ambos para o servidor iniciado).

Interface do Navegador

npm run dev

O Inspector exibe uma URL como http://localhost:6274. Abra-a, mude para a aba Ferramentas, escolha uma ferramenta (ex.: get-template), preencha os parâmetros como JSON e clique em Executar. A resposta do Mailtrap aparece no painel abaixo.

CLI

Para chamadas pontuais sem a interface, use npm run mcp:cli. Passe as flags CLI do Inspector após -- para que o npm as encaminhe literalmente:

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg [email protected]

Executando o Servidor MCPB

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Para desenvolvimento com o MCP Inspector:

npm run dev:mcpb

Tratamento de Erros

Este servidor utiliza tratamento de erros estruturado alinhado com as convenções MCP:

  • VALIDATION_ERROR: Falhas de validação de entrada
  • CONFIGURATION_ERROR: Configuração ausente ou inválida
  • EXECUTION_ERROR: Erros de execução em tempo de execução
  • TIMEOUT: Tempo limite da operação (padrão de 30 segundos)

Os erros incluem mensagens acionáveis e são registrados em formato estruturado.

Segurança

  • Entrada validada via esquemas Zod
  • Variáveis de ambiente tratadas de forma segura
  • Proteção de tempo limite nas operações (30 segundos)
  • Detalhes sensíveis sanitizados na saída de erros

Registro de Logs

Logs JSON estruturados com níveis: INFO, WARN, ERROR, DEBUG.

Habilite o log de depuração definindo DEBUG=true.

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

Importante: O servidor grava logs no stderr para que o stdout permaneça reservado para quadros JSON-RPC. Isso evita que os hosts encontrem erros de parsing JSON devido a logs intercalados.

Exemplo de análise de log usando jq:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

Solução de Problemas

Problemas comuns:

  1. Token de API ausente: certifique-se de que MAILTRAP_API_TOKEN está definido
  2. Sandbox não funciona: forneça test_inbox_id na chamada da ferramenta ou defina a variável de ambiente MAILTRAP_TEST_INBOX_ID
  3. Erros de tempo limite: verifique a conectividade de rede e o status da API do Mailtrap
  4. Erros de validação: certifique-se de que todos os campos obrigatórios foram fornecidos

Contribuindo

Relatórios de bugs e pull requests são bem-vindos no GitHub. Este projeto visa ser um espaço seguro e acolhedor para colaboração, e espera-se que os contribuidores sigam o código de conduta.

Licença

O pacote está disponível como código aberto sob os termos da Licença MIT.

Código de Conduta

Espera-se que todos que interajam nos repositórios de código, rastreadores de issues, salas de chat e listas de discussão do projeto Mailtrap sigam o código de conduta.