Mailgun

Mailgun MCP Server

Visão Geral

Um servidor Model Context Protocol (MCP) para Mailgun que oferece aos agentes de IA uma interface prática e orientada a fluxos de trabalho para enviar e-mails, diagnosticar a entregabilidade e gerenciar operações da conta.

[!NOTE] Este servidor MCP é executado localmente em sua máquina e se comunica via stdio. Atualmente, o Mailgun não oferece uma versão hospedada deste servidor.

Capacidades

• Mensagens — Enviar e-mails, recuperar mensagens armazenadas, reenviar mensagens
• Domínios — Visualizar detalhes do domínio, verificar configuração de DNS, gerenciar configurações de rastreamento (cliques, aberturas, cancelamento de inscrição)
• Webhooks — Listar, criar e atualizar webhooks de eventos
• Rotas — Visualizar e atualizar regras de roteamento de e-mails recebidos
• Listas de E-mails — Criar, visualizar e atualizar listas de e-mails e seus membros
• Modelos — Criar, visualizar e atualizar modelos de e-mail com versionamento
• Analytics — Consultar métricas de envio, métricas de uso e logs
• Estatísticas — Visualizar estatísticas agregadas por domínio, tag, provedor, dispositivo e país
• Supressões — Visualizar devoluções (bounces), cancelamentos de inscrição, reclamações e entradas da lista de permissões
• IPs e Conjuntos de IPs — Visualizar atribuições de IP e configuração de conjuntos de IPs dedicados
• Classificação de Devoluções — Analisar tipos de devolução e problemas de entrega
• Validação — Validar a entregabilidade e a sintaxe de endereços de e-mail antes do envio (validate)
• Otimizar (Posicionamento na Caixa de Entrada) — Recuperar resultados de testes de posicionamento na caixa de entrada/testes semente para avaliar a entregabilidade (optimize)
• Inspecionar (Pré-visualização de E-mail) — Recuperar resultados de testes de renderização e pré-visualização de e-mail em diferentes clientes (inspect)
• Limites da Conta — Visualizar limites de envio mensais personalizados

Os rótulos entre parênteses acima (validate, optimize, inspect) são as tags de produto usadas pela filtragem por tag. Todas as outras capacidades são registradas sob a tag send.

[!NOTE] As ferramentas são limitadas a operações de leitura e atualização — nenhuma operação de exclusão é exposta, o que mantém o raio de impacto de uma ação não intencional pequeno. Consulte Considerações de Segurança.

Como funciona

O servidor é orientado por OpenAPI. Na inicialização, ele analisa uma especificação OpenAPI empacotada do Mailgun e registra uma lista de permissões curada de endpoints como ferramentas MCP, gerando o esquema de entrada de cada ferramenta (via Zod) a partir da especificação. Cada ferramenta é anotada com uma tag de produto do Mailgun (send, validate, optimize ou inspect). Todas as ferramentas correspondentes são registradas antecipadamente — não há carregamento sob demanda ou preguiçoso. A filtragem por tag é aplicada na inicialização para definir o escopo de quais ferramentas são registradas, para que um determinado fluxo de trabalho possa expor apenas os produtos de que precisa.

Pré-requisitos

• Node.js (v20.12 ou superior)
• Conta Mailgun e chave de API

Instalação

O servidor é publicado no npm como @mailgun/mcp-server e é executado via stdio. A maioria dos clientes pode iniciá-lo sob demanda com npx, portanto, não há necessidade de instalação global. Em cada trecho abaixo, substitua YOUR-mailgun-api-key por uma chave das suas configurações de segurança da API do Mailgun.

[!TIP] Se sua conta estiver hospedada na região da UE do Mailgun, adicione "MAILGUN_API_REGION": "eu" ao bloco env (ou -e MAILGUN_API_REGION=eu na CLI). O padrão é us.

Claude Code

claude mcp add mailgun -e MAILGUN_API_KEY=YOUR-mailgun-api-key -- npx -y @mailgun/mcp-server

Em seguida, execute /mcp no Claude Code para confirmar que o servidor mailgun está conectado.

Claude Desktop

Abra Configurações → Desenvolvedor → Editar Configuração ou edite o arquivo diretamente:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
        "MAILGUN_API_REGION": "us"
      }
    }
  }
}

Cursor

Abra a paleta de comandos e escolha Cursor Settings → MCP → Add new global MCP server e adicione:

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Codex

codex mcp add mailgun \
  --env MAILGUN_API_KEY=YOUR-mailgun-api-key \
  -- npx -y @mailgun/mcp-server

VS Code (GitHub Copilot)

Adicione o seguinte ao seu settings.json:

{
  "mcp": {
    "servers": {
      "mailgun": {
        "command": "npx",
        "args": ["-y", "@mailgun/mcp-server"],
        "env": {
          "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
        }
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Gemini CLI

Adicione ao ~/.gemini/settings.json:

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Configuração

Variáveis de ambiente

Variável	Obrigatória	Padrão	Descrição
MAILGUN_API_KEY	Sim	—	Sua chave de API do Mailgun
MAILGUN_API_REGION	Não	us	Região da API: us ou eu
MAILGUN_API_HOSTNAME	Não	(derivado da região)	Substitui o nome do host da API (ex.: api.eu.mailgun.net). Tem precedência sobre a região.
MAILGUN_MCP_TAGS	Não	(todas)	Tags de produto separadas por vírgula para habilitar. Equivalente a --tags. A flag da CLI tem precedência.

Opções da CLI

Passe as flags após o nome do pacote no args do seu cliente (ex.: ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Flag	Descrição
--tags <list>	Tags de produto separadas por vírgula para habilitar (padrão: todas). Válidas: send, validate, optimize, inspect.
--list-tags	Imprime os valores de tag válidos e sai.
--help, -h	Mostra o uso e sai.

Filtragem por tag

Você pode definir o escopo de quais ferramentas o servidor registra para uma ou mais tags de produto do Mailgun. Isso é útil para restringir o conjunto de ferramentas mostrado ao modelo — por exemplo, expondo apenas ferramentas de validação para um fluxo de trabalho que não precisa de capacidades de envio.

Tags válidas: send, validate, optimize, inspect. Quando não especificado, todas as ferramentas são registradas (padrão atual).

A filtragem usa semântica OU: uma ferramenta é registrada se qualquer uma de suas tags aparecer no conjunto ativo.

Via flag da CLI — passe --tags no args da configuração do seu cliente MCP:

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Via variável de ambiente — defina MAILGUN_MCP_TAGS (a flag da CLI prevalece se ambas estiverem presentes):

"env": {
  "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
  "MAILGUN_MCP_TAGS": "validate,inspect"
}

[!TIP] Execute o binário com --list-tags para imprimir os valores de tag suportados ou --help para o uso completo. Tags desconhecidas são rejeitadas na inicialização com uma mensagem de erro clara.

Exemplos de Prompts

Enviar um E-mail

Can you send an email to EMAIL_HERE with a funny email body that makes it sound
like it's from the IT Desk from Office Space? Please use the sending domain
DOMAIN_HERE, and make the email from "postmaster@DOMAIN_HERE"!

[!NOTE] Alguns clientes MCP exigem um plano pago para invocar ferramentas que enviam dados. Se o envio falhar silenciosamente, verifique o plano do seu cliente.

Buscar e Visualizar Estatísticas de Envio

Would you be able to make a chart with email delivery statistics for the past week?

Gerenciar Modelos

Create a welcome email template for new signups on my domain DOMAIN_HERE.
Include a personalized greeting and a call-to-action button.

Investigar a Entregabilidade

Can you check the bounce classification stats for my account and tell me
what the most common bounce reasons are?

Solucionar Problemas de DNS

Check the DNS verification status for my domain DOMAIN_HERE and tell me
if anything needs fixing.

Revisar Supressões

Are there any unsubscribes or complaints for DOMAIN_HERE? Summarize the
top offenders.

Gerenciar Regras de Roteamento

List all my inbound routes and explain what each one does.

Criar uma Lista de E-mails

Create a mailing list called announcements@DOMAIN_HERE and add these
members: alice@example.com, bob@example.com.

Comparar Domínios

Compare my sending volume and delivery rates across all my domains for
the past month.

Engajamento por Região

Break down my email engagement by country and device for DOMAIN_HERE.

Revisar Configurações de Rastreamento

List all my domains and show which ones have tracking enabled for clicks
and opens.

Validar um Endereço de E-mail

Validate the email address EMAIL_HERE and tell me whether it's safe to send to.

Verificar Posicionamento na Caixa de Entrada (Otimizar)

Pull the inbox placement results for seed test RESULT_ID_HERE and summarize
where my message landed (inbox, spam, or missing) by provider.

Pré-visualizar um E-mail (Inspecionar)

Get the email preview results for test TEST_ID_HERE and tell me if the email
renders correctly across clients.

Desenvolvimento

Executar a partir do código-fonte

O servidor é escrito em TypeScript. Clone, instale, compile e teste:

git clone https://github.com/mailgun/mailgun-mcp-server.git
cd mailgun-mcp-server
npm install
npm run build
npm test

npm run build compila src/ para dist/ e copia a especificação OpenAPI empacotada. Aponte seu cliente MCP para o ponto de entrada compilado em vez de npx (use um caminho absoluto):

{
  "mcpServers": {
    "mailgun": {
      "command": "node",
      "args": ["/absolute/path/to/mailgun-mcp-server/dist/mailgun-mcp.js"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Testes ao vivo durante a edição

Servidores MCP são processos stdio de longa duração que não recarregam automaticamente, então o ciclo é: recompilar ao salvar e reconectar o cliente para capturar as mudanças.

1. Execute npm run build uma vez para que dist/openapi.yaml esteja no lugar.

2. Mantenha o compilador TypeScript em execução para recompilar dist/ a cada salvamento:

   npx tsc --watch
   

3. Aponte um cliente MCP separado (ou o MCP Inspector, abaixo) para dist/mailgun-mcp.js. Após uma alteração, reinicie a sessão do cliente MCP para carregar a nova compilação.

Testando com o MCP Inspector

O MCP Inspector permite exercitar as ferramentas sem um cliente completo. Compile primeiro e, em seguida, inicie-o contra o servidor compilado:

npm run build
MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js

Abra a interface do Inspector, clique em Connect e use List Tools para verificar se o servidor está funcionando. Para testar um conjunto de ferramentas filtrado, anexe flags após o caminho do servidor:

MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js --tags validate,inspect

Hooks de pré-commit

npm install instala um hook git de pré-commit (via husky) que executa oxlint --fix e oxfmt nos arquivos TypeScript/JavaScript preparados e executa npm run check:versions. Problemas corrigíveis são automaticamente corrigidos e re-preparados; commits que introduzem erros de lint não corrigíveis ou incompatibilidades de sincronização de versão são rejeitados. Se você já tinha um clone local antes desta alteração, execute npm install uma vez para instalar o hook.

Nota sobre a adição de endpoints

Ao adicionar um novo endpoint, se você usar uma string simples para sua definição, ele será padronizado como sendo marcado com o tipo de produto send no campo _meta. Se desejar marcá-lo como um produto diferente, use a versão de objeto do tipo EndpointEntry.

Considerações de Segurança

Isolamento da chave de API

Sua chave de API do Mailgun é passada como uma variável de ambiente e nunca é exposta ao modelo de IA em si — ela é usada apenas pelo processo do servidor MCP para autenticar solicitações. O servidor não registra chaves de API, parâmetros de solicitação ou dados de resposta.

Execução local

O servidor é executado localmente em sua máquina. Toda a comunicação com a API do Mailgun é feita via HTTPS com validação de certificado TLS aplicada. Nenhum dado é enviado a serviços de terceiros além da API do Mailgun.

Permissões da chave de API

Use uma chave de API dedicada do Mailgun com permissões limitadas apenas às operações de que você precisa. O servidor expõe operações de leitura e atualização, mas não expõe nenhuma operação de exclusão, o que limita o raio de impacto de ações não intencionais.

Limitação de taxa

O servidor não implementa limitação de taxa do lado do cliente. Cada chamada de ferramenta da IA se traduz diretamente em uma solicitação à API do Mailgun. O servidor depende dos limites de taxa do lado do servidor do Mailgun para evitar abusos — solicitações que excedam esses limites retornarão um erro ao assistente de IA.

Injeção de prompt

Como em qualquer servidor MCP, um prompt criado ou adversário pode enganar o assistente de IA para que ele execute operações que você não pretendia — por exemplo, modificar configurações de rastreamento ou ler membros de listas de e-mails. Revise as confirmações de chamada de ferramenta do seu assistente de IA antes de aprovar ações, especialmente em contextos de prompt não confiáveis.

URLs de Webhook

As operações de criação e atualização de webhook aceitam URLs arbitrárias fornecidas pelo assistente de IA. O servidor MCP passa essas URLs para a API do Mailgun sem validação adicional. O Mailgun é responsável por validar os destinos dos webhooks. Certifique-se de que seu assistente de IA não defina URLs de webhook para endereços internos ou confidenciais não intencionais.

Validação de entrada

Todos os parâmetros da ferramenta são validados em relação à especificação OpenAPI do Mailgun usando esquemas Zod. No entanto, a validação depende da precisão da especificação OpenAPI, e alguns parâmetros de casos extremos podem recorrer à validação permissiva. A API do Mailgun realiza sua própria validação do lado do servidor como uma camada adicional de proteção.

Depuração

O servidor MCP se comunica via stdio. Consulte o Guia de Depuração do MCP para solução de problemas.

Licença

Apache 2.0 — consulte LICENSE para obter detalhes.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request ou abrir uma Issue.