Mailtrap

oficial

Integra-se com Mailtrap Email API.

GitHub
63

O que você pode fazer com Mailtrap MCP?

  • Enviar e-mails transacionais — Solicite o envio de um e-mail via send-email com conteúdo inline ou modelo, incluindo CC/BCC e variáveis personalizadas.
  • Gerenciar modelos de e-mail — Use list-templates, create-template, update-template ou delete-template para manter designs de e-mail reutilizáveis.
  • Inspecionar logs de entrega — Consulte list-email-logs com filtros como destinatário, status ou data e aprofunde-se nos detalhes com get-email-log-message.
  • Testar e-mails em sandbox — Envie para uma caixa de entrada de teste via send-sandbox-email e revise as mensagens com get-sandbox-messages e show-sandbox-email-message.
  • Analisar desempenho de envio — Obtenha taxas de entrega, rejeição e engajamento via get-sending-stats, opcionalmente segmentadas por domínio ou categoria.
  • Configurar infraestrutura de envio — Gerencie list-sending-domains, crie ou exclua domínios e recupere instruções de configuração de DNS.

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 de:

  1. Criar uma conta 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 contas 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, registros de e-mail, listagem/exibição de sandbox e domínios de envio. Opcional apenas para as ferramentas de envio (send-email, send-sandbox-email e as ferramentas batch-send-*).

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

  • DEFAULT_FROM_EMAIL - Remetente padrão quando from não é fornecido para send-email, send-sandbox-email ou as ferramentas batch-send-* (onde preenche base.from). Permite alternar o remetente por chamada via parâmetro from.
  • MAILTRAP_SANDBOX_ID - ID de sandbox padrão para ferramentas de sandbox quando sandbox_id não é fornecido. Permite alternar entre sandboxes por chamada via parâmetro sandbox_id.
  • MAILTRAP_TEST_INBOX_ID - ID de caixa de entrada de teste padrão para ferramentas de sandbox quando test_inbox_id não é fornecido. Permite alternar entre caixas de entrada por chamada via parâmetro test_inbox_id. Alias legado para MAILTRAP_SANDBOX_ID, ainda aceito como fallback.
  • 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ória para ferramentas de organização (separado de MAILTRAP_API_TOKEN).

Instalação rápida

Install in Cursor

Install with Node in VS Code

CLI Smithery

O 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 fornece um processo de instalaçã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": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Se você estiver usando asdf para gerenciar 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": "your_sender@example.com",
        "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)

Depois, 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": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

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

Pacote MCP (MCPB)

Para instalação fácil em hosts que suportam Pacotes MCP, você pode distribuir um arquivo de pacote .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

Depois de configurado, você pode pedir ao agente para enviar e-mails e gerenciar templates, por exemplo:

Operações de envio de e-mail:

  • "Envie um e-mail para john.doe@example.com com o assunto 'Reunião amanhã' e um lembrete amigável sobre nossa próxima reunião."
  • "Envie um e-mail para sarah@example.com sobre a atualização do projeto e copie a equipe em team@example.com"
  • "Envie o template de boas-vindas (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) para new@example.com com as variáveis { name: 'Alex' }"
  • "Envie um e-mail sandbox para test@example.com com o assunto 'Template de teste' para visualizar como nosso e-mail de boas-vindas fica"

Registros de e-mail (depuração de entrega):

  • "Liste meus registros de e-mail enviados recentemente"
  • "Mostre os registros de e-mail para e-mails enviados para user@example.com"
  • "Obtenha a mensagem do registro de e-mail 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 por domínio do último mês"
  • "Quais são minhas estatísticas de e-mail por categoria de 2025-01-01 a 2025-01-31?"

Operações de sandbox:

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

Operações de template:

  • "Liste todos os templates de e-mail na minha conta Mailtrap"
  • "Crie um novo template de e-mail chamado 'E-mail de boas-vindas' com o 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 e-mail transacional pelo Mailtrap. Suporta dois modos mutuamente exclusivos — conteúdo inline (subject + text/html) ou baseado em template (template_uuid).

Parâmetros:

  • from (opcional): Remetente como { email, name? } (uma string de e-mail simples também é aceita em tempo de execução). Se não fornecido, DEFAULT_FROM_EMAIL é usado.
  • to (opcional): Matriz de destinatários como objetos { email, name? } (strings de e-mail simples, ou um único endereço não-matriz, também são aceitos em tempo de execução). Opcional se cc ou bcc for fornecido; pelo menos um de to / cc / bcc deve conter um destinatário.
  • cc (opcional): Matriz de destinatários em CC como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • bcc (opcional): Matriz de destinatários em CCO como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • subject (condicional): Linha de assunto do e-mail. Obrigatória para envios inline; deve ser omitida quando template_uuid estiver definido.
  • text (condicional): Texto do corpo do e-mail. 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ória (junto ou em vez de text) para envios inline; deve ser omitida quando template_uuid estiver definido.
  • category (opcional): Categoria do e-mail para rastreamento e análises. Deve ser omitida quando template_uuid estiver definido.
  • template_uuid (opcional): Use um template de e-mail Mailtrap em vez de conteúdo inline. Quando definido, subject / text / html / category devem ser omitidos (de acordo com a API 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 e-mails transacionais em uma única chamada de API Mailtrap (stream de envio padrão). Campos compartilhados vão em base; substituições por destinatário vão em requests[]. Cada solicitaçã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 base com cada solicitação.

Parâmetros:

  • base (opcional): Objeto com campos compartilhados em todo o lote.
    • from (opcional): Remetente como { email, name? } (uma string de e-mail simples também é aceita em tempo de execução). Cai para DEFAULT_FROM_EMAIL.
    • reply_to (opcional): Endereço de resposta.
    • subject / text / html / category (opcional, modo inline): Conteúdo padrão para cada solicitaçã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 valores de string).
    • headers (opcional): Cabeçalhos personalizados padrão.
  • requests (obrigatório): Matriz não vazia de mensagens por destinatário. Cada entrada tem:
    • to (opcional): Matriz de destinatários como objetos { email, name? } (strings de e-mail simples, ou um único endereço não-matriz, também são aceitos em tempo de execução). 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 cai para o valor base correspondente.
    • custom_variables, headers (opcional).

batch-send-bulk-email

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

list-email-logs

Lista registros de e-mail enviados (histórico de entrega) com paginação e filtros opcionais. Use para depurar problemas de entrega direto 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 e-mail do remetente; use com from_operator (padrão: ci_equal).
  • to_email (opcional): Filtrar por e-mail 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 e-mail; use com subject_operator (padrão: ci_contain). Use subject_operator: empty/not_empty para filtrar pela presença do 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 stream: 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 e-mail; use com category_operator: equal, not_equal.

Todos os parâmetros são opcionais.

get-email-log-message

Obtém uma única mensagem de registro de e-mail por ID (UUID): um resumo legível (de, para, assunto, horário de envio, status, categoria, stream, engajamento, contexto de entrega) e depois o 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 e-mail (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 e-mail (taxas de entrega, rejeição, abertura, clique, spam) para um intervalo de datas. Opcionalmente, detalhe por domínio, categoria, provedor de serviço de e-mail ou data. Verifique as taxas de entrega sem sair do editor.

Parâmetros:

  • start_date (obrigatório): Data de início para o intervalo de estatísticas (YYYY-MM-DD)
  • end_date (obrigatório): Data de término para o intervalo de estatísticas (YYYY-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 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: "Geral")

list-templates

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

Parâmetros:

  • Nenhum parâmetro necessário

get-template

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

Parâmetros:

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

update-template

Atualiza um modelo de e-mail existente.

Parâmetros:

  • template_id (obrigatório): ID do modelo a atualizar
  • 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 excluir

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 { email, name? } (uma string de e-mail simples também é aceita em tempo de execução). Se não for fornecido, DEFAULT_FROM_EMAIL é usado.
  • to (opcional): Array de destinatários como objetos { email, name? } (strings de e-mail simples no array, ou uma string separada por vírgulas de e-mails simples, também são aceitas em tempo de execução). 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 como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • bcc (opcional): Array de destinatários em CCO como objetos { email, name? } (strings de e-mail simples também são aceitas em tempo de execução).
  • subject (condicional): Linha de assunto do e-mail. Obrigatória para envios inline; deve ser omitida quando template_uuid estiver definido.
  • text (condicional): Texto do corpo do e-mail. 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ória (junto ou em vez de text) para envios inline; deve ser omitida quando template_uuid estiver definido.
  • category (opcional): Categoria do e-mail para rastreamento. Deve ser omitida quando template_uuid estiver definido.
  • template_uuid (opcional): Use 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.

batch-send-sandbox-email

Envia um lote de e-mails para sua caixa de entrada de teste do Mailtrap em uma única chamada de API, sem entregar a destinatários reais. Mesma forma base + requests[], validação e regras de inline-vs-template que batch-send-transactional-email — a diferença é que esta ferramenta roteia a chamada pelo endpoint de sandbox para uma única caixa de entrada de teste.

Parâmetros:

  • sandbox_id (opcional): ID do sandbox do Mailtrap (caixa de entrada de teste). Obrigatório a menos que MAILTRAP_SANDBOX_ID esteja definido; passe por chamada para direcionar um sandbox específico.
  • base (opcional), requests (obrigatório): Veja batch-send-transactional-email acima.

[!NOTE] Para ferramentas de 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. Ferramentas que usam sandbox_id usam MAILTRAP_SANDBOX_ID primeiro.

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 em HTML e texto.

Parâmetros:

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

[!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 de sandbox por ID, incluindo suas caixas de entrada e contagens de e-mail.

Parâmetros:

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

update-sandbox-project

Renomeia um projeto de sandbox existente.

Parâmetros:

  • project_id (obrigatório): ID do projeto a atualizar
  • 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 necessário

mark-sandbox-as-read

Marca todas as mensagens em um sandbox como lidas.

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox no qual agir

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 no qual agir

enable-sandbox-email-address

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

Parâmetros:

  • sandbox_id (obrigatório): ID do sandbox no qual agir

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 no qual agir

forward-sandbox-message

Encaminha uma mensagem de 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 de sandbox a encaminhar
  • email (obrigatório): Endereço de e-mail para o qual encaminhar a mensagem

update-sandbox-message

Marca uma mensagem de 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 de sandbox a atualizar
  • is_read (obrigatório): true marca como lida, false marca como não lida

delete-sandbox-message

Exclui uma única mensagem de sandbox.

Parâmetros:

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

get-sandbox-message-spam-score

Obtém o relatório de spam do SpamAssassin para uma mensagem de 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 de sandbox

get-sandbox-message-html-analysis

Obtém o relatório de análise HTML para uma mensagem de 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 de sandbox

get-sandbox-message-headers

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

Parâmetros:

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

get-sandbox-message-html

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

Parâmetros:

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

get-sandbox-message-text

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

Parâmetros:

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

get-sandbox-message-raw

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

Parâmetros:

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

get-sandbox-message-eml

Obtém a mensagem renderizada como 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 de sandbox

get-sandbox-message-html-source

Obtém o código-fonte HTML não renderizado de uma mensagem de sandbox (HTML antes de qualquer transformação 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 de sandbox

list-sandbox-attachments

Lista todos os anexos em uma mensagem de 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 de sandbox

get-sandbox-attachment

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

Parâmetros:

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

list-sending-domains

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

Parâmetros:

  • Nenhum parâmetro necessário

get-sending-domain

Obtém um domínio de envio pelo ID e seu status de verificação (incluindo registros DNS). Opcionalmente, inclua instruções de configuração de 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, adiciona instruções de configuração de 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.: example.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 por email as instruções de configuração de DNS para um domínio de envio para um endereço específico. Ú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 email para o qual enviar as instruções de configuração de DNS

list-suppressions

Lista ou pesquisa supressões (rejeições permanentes, reclamações de spam, cancelamentos de assinatura, importações manuais). Retorna até 1000 resultados por chamada.

Parâmetros:

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

delete-suppression

Exclui uma supressão pelo ID. O Mailtrap retomará a entrega para este email, 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 necessário

get-webhook

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

Parâmetros:

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

create-webhook

Cria um webhook. A resposta inclui um signing_secret para verificar assinaturas de payload do webhook — esse segredo é retornado apenas na criação, então salve-o agora. Se você o perder, recrie o webhook.

Parâmetros:

  • url (obrigatório): URL para o qual o Mailtrap enviará eventos de webhook via POST
  • webhook_type (obrigatório): "email_sending", "audit_log" ou "inbound_receiving"
  • active (opcional, booleano): padrão é true
  • payload_format (opcional): "json" ou "jsonlines". Padrão: "json"
  • sending_stream (opcional, apenas email_sending): "transactional" ou "bulk"
  • event_types (opcional, apenas email_sending): matriz de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (opcional, apenas email_sending): ID do domínio de envio para limitar este webhook a ele
  • inbound_inbox_id (opcional, apenas inbound_receiving): ID da caixa de entrada de inbound à qual o webhook está vinculado; omita para aplicar a todas as caixas de entrada da conta

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): Ativar ou desativar o webhook
  • payload_format (opcional): "json" ou "jsonlines"
  • event_types (opcional, apenas email_sending): matriz de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • inbound_inbox_id (opcional, apenas inbound_receiving): ID da caixa de entrada de inbound à qual o webhook está vinculado

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 email. 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 email

create-contact

Cria um novo contato.

Parâmetros:

  • email (obrigatório): Endereço de email
  • fields (opcional): Valores de campos personalizados chaveados por tag de mesclagem (ex.: first_name). Valores string, número ou booleano
  • list_ids (opcional): IDs de listas de contatos para assinar este contato
  • unsubscribed (opcional, booleano): Criar o contato no status unsubscribed

update-contact

Atualiza um contato existente identificado por ID ou email. list_ids substitui o conjunto completo de associações do contato; list_ids_included/list_ids_excluded adiciona/remove sem afetar o restante.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou email
  • email (opcional): Novo endereço de email
  • fields (opcional): Valores de campos personalizados chaveados por tag de mesclagem
  • list_ids (opcional): Substitui o conjunto de associações por esta lista exata
  • list_ids_included (opcional): IDs de listas para adicionar (aditivo)
  • list_ids_excluded (opcional): IDs de listas para remover
  • unsubscribed (opcional, booleano): Defina como unsubscribed (verdadeiro) ou subscribed (falso)

delete-contact

Exclui permanentemente um contato por ID ou email. 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 email

create-contact-event

Registra um evento de contato associado a um contato (por ID ou email). Usado para acionar automações de listas de contatos.

Parâmetros:

  • contact_identifier (obrigatório): ID do contato ou email
  • name (obrigatório): Nome do evento (corresponde aos gatilhos de automação)
  • params (obrigatório): Objeto com pares chave/valor arbitrários. Os valores podem ser string, número, booleano ou nulo

list-contact-lists

Lista todas as listas de contatos da conta.

Parâmetros:

  • search (opcional): Filtra listas de contatos por nome (correspondência sem diferenciar maiúsculas/minúsculas), ex.: news

get-contact-list

Obtém uma lista de contatos pelo ID.

Parâmetros:

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

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 necessá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 na conta e é usado como nome do placeholder em variáveis de modelo.

Parâmetros:

  • name (obrigatório): Nome de exibição (ex.: "Primeiro Nome")
  • merge_tag (obrigatório): Nome do 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 job de importação; consulte o status dele com get-contact-import.

Parâmetros:

  • contacts (obrigatório): Matriz de entradas de contato. Cada entrada precisa de:
    • email (obrigatório): Endereço de email do contato
    • fields (opcional): Valores de campos personalizados chaveados por tag de mesclagem (valores string ou número)
    • list_ids_included (opcional): IDs de listas para adicionar o contato
    • list_ids_excluded (opcional): IDs de listas para remover o contato

get-contact-import

Obtém o status de um job de importação de contatos (criado/iniciado/concluído/falhou) com contagens de criados/atualizados/acima do limite.

Parâmetros:

  • import_id (obrigatório): ID do job de importação de contatos

create-contact-export

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

Parâmetros:

  • filters (obrigatório): Matriz de objetos de filtro. Cada um tem:
    • name (obrigatório): Campo a ser filtrado (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, número, booleano ou matriz)

get-contact-export

Obtém o status de um job 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 do job 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 necessário

get-billing-usage

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

Parâmetros:

  • Nenhum parâmetro necessá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 (matriz de strings)
  • inbox_ids (opcional): Filtrar por IDs de caixa de entrada da sandbox (matriz de strings)
  • project_ids (opcional): Filtrar por IDs de projeto da sandbox (matriz de strings)

remove-account-access

Remove um acesso à conta pelo ID. Para especificadores User, isso revoga as permissões deles; para especificadores Invite ou ApiToken, remove o especificador por completo. 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, cobrança, conta) aos quais o token de API tem acesso de administrador, aninhados por hierarquia.

Parâmetros:

  • Nenhum parâmetro necessá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 de acesso da conta de destino
  • permissions (obrigatório): Matriz de entradas de permissão. Cada uma contém:
    • resource_id (obrigatório): ID do recurso (número 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 verdadeiro, remove esta permissão em vez de criar/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 em que o token completo é retornado, então salve-o imediatamente. Se você o perder, recrie o token.

Parâmetros:

  • name (obrigatório): Nome de exibição do token
  • resources (opcional): Matriz de permissões de recursos para escopar o token. Cada entrada contém:
    • 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 (visualizador)

get-api-token

Obtém um token de API por ID. Retorna apenas metadados — o valor secreto do token não é retornado aqui (somente em 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 por ID. A resposta inclui o novo valor secreto token — retornado somente nesta chamada, então salve-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 por ID. O token não pode 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 subcontas da 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 da nova subconta

list-inbound-folders

Lista todas as pastas de entrada da conta. Retorna um resumo formatado.

Parâmetros:

  • Nenhum parâmetro obrigatório

get-inbound-folder

Obtém uma pasta de entrada por ID. Retorna o registro completo da pasta como JSON.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada

create-inbound-folder

Cria uma nova pasta de entrada.

Parâmetros:

  • name (obrigatório): O nome da pasta

update-inbound-folder

Renomeia uma pasta de entrada.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • name (obrigatório): O novo nome da pasta

delete-inbound-folder

Exclui permanentemente uma pasta de entrada junto com todas as suas caixas de entrada.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada

list-inbound-inboxes

Lista todas as caixas de entrada em uma pasta de entrada. Retorna um resumo formatado.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada

get-inbound-inbox

Obtém uma caixa de entrada por ID. Retorna o registro completo da caixa de entrada como JSON.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • inbox_id (obrigatório): ID da caixa de entrada

create-inbound-inbox

Cria uma nova caixa de entrada em uma pasta.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • name (obrigatório): O nome da caixa de entrada
  • domain_id (opcional): Anexar a um domínio de envio personalizado (caixa de entrada catch-all). Omita para uma caixa de entrada hospedada pelo Mailtrap

update-inbound-inbox

Renomeia uma caixa de entrada.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • inbox_id (obrigatório): ID da caixa de entrada
  • name (obrigatório): O novo nome da caixa de entrada

delete-inbound-inbox

Exclui permanentemente uma caixa de entrada.

Parâmetros:

  • folder_id (obrigatório): ID da pasta de entrada
  • inbox_id (obrigatório): ID da caixa de entrada

list-inbound-messages

Lista mensagens recebidas em uma caixa de entrada (paginação por cursor). Retorna um resumo formatado com uma dica de próxima página quando há mais resultados.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • last_id (opcional): Cursor de paginação do last_id de uma resposta anterior

get-inbound-message

Obtém uma única mensagem recebida com seu corpo completo e URLs de download de anexos. Retorna o registro completo da mensagem como JSON.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem

delete-inbound-message

Exclui permanentemente uma mensagem recebida.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem

reply-to-inbound-message

Responde a uma mensagem recebida (envia para o remetente original). Envia um e-mail real. Endereços aceitam uma string de e-mail simples ou { email, name? }.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem a ser respondida
  • text / html (pelo menos um recomendado): Corpo da resposta
  • from (opcional): Remetente. Rejeitado para caixas de entrada hospedadas pelo Mailtrap; obrigatório para caixas de entrada com domínio personalizado
  • cc / bcc / reply_to (opcional): Endereços adicionais
  • category (opcional): Categoria da mensagem
  • attachments (opcional): Matriz de { content (base64), filename, type?, disposition?, content_id? }
  • headers / custom_variables (opcional): Objetos de valores de string

reply-all-to-inbound-message

Responde a uma mensagem recebida e copia os outros destinatários da mensagem original. Envia um e-mail real. Mesmos parâmetros de reply-to-inbound-message.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem a ser respondida
  • Além dos mesmos campos opcionais de envio de reply-to-inbound-message

forward-inbound-message

Encaminha uma mensagem recebida para novos destinatários. Envia um e-mail real.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • message_id (obrigatório): ID da mensagem a ser encaminhada
  • to (obrigatório): Pelo menos um destinatário (string de e-mail simples ou { email, name? }, ou uma matriz)
  • Além dos mesmos campos opcionais de envio de reply-to-inbound-message

list-inbound-threads

Lista conversas (threads) em uma caixa de entrada (paginação por cursor). Retorna um resumo formatado com uma dica de próxima página quando há mais resultados.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • last_id (opcional): Cursor de paginação do last_id de uma resposta anterior

get-inbound-thread

Obtém uma única conversa (thread) com suas mensagens incorporadas (da mais antiga para a mais recente). Retorna o registro completo da conversa como JSON.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • thread_id (obrigatório): ID da conversa

delete-inbound-thread

Exclui permanentemente uma conversa (thread) de entrada.

Parâmetros:

  • inbox_id (obrigatório): ID da caixa de entrada
  • thread_id (obrigatório): ID da conversa

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 Setup.

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": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Se você estiver usando o asdf para gerenciar o Node.js, use 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": "your_sender@example.com",
        "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 Setup.

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

Testes

Executando ferramentas com o Mailtrap real

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

Ambas exigem que o bundle seja compilado primeiro:

npm run build

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

Interface de navegador

npm run dev

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

CLI

Para chamadas únicas sem a interface, use npm run mcp:cli. Passe os flags de CLI do Inspector após -- para que o npm os encaminhe exatamente como estão:

# 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=devops@example.com

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 usa tratamento de erros estruturado, alinhado às convenções do 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 de operação (padrão de 30 segundos)

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

Segurança

  • Entrada validada por meio de esquemas Zod
  • Variáveis de ambiente tratadas com segurança
  • Proteção contra 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.

Ative o registro de debug 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 análise JSON devido a logs intercalados.

Exemplo de análise de logs 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: verifique se MAILTRAP_API_TOKEN está definido
  2. Sandbox não funcionando: 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: verifique se 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 interagem nos codebases, rastreadores de issues, salas de chat e listas de e-mail do projeto Mailtrap sigam o código de conduta.