Mailgun MCP Server

oficial

Interaja com a API do Mailgun.

GitHub
56

Documentação

Servidor MCP do Mailgun

MCP

Visão Geral

Um servidor Model Context Protocol (MCP) para o 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.

Nota: Este servidor MCP é executado localmente em sua máquina. O Mailgun não oferece atualmente uma versão hospedada deste servidor.

Capacidades

  • Mensagens — Enviar e-mails, recuperar mensagens armazenadas, reenviar mensagens
  • Domínios — Visualizar detalhes do domínio, verificar a configuração de DNS, gerenciar configurações de rastreamento (cliques, aberturas, cancelamentos de inscrição)
  • Webhooks — Listar, criar, atualizar e excluir webhooks de eventos
  • Rotas — Visualizar e atualizar regras de roteamento de e-mails de entrada
  • Listas de E-mails — Criar e gerenciar listas de e-mails e seus membros
  • Modelos — Criar e gerenciar 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, 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

Pré-requisitos

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

Início Rápido

Configuração

Adicione o seguinte à configuração do seu cliente MCP:

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

Variáveis de Ambiente

VariávelObrigatóriaPadrãoDescrição
MAILGUN_API_KEYSim—Sua chave de API do Mailgun
MAILGUN_API_REGIONNãousRegião da API: us ou eu
MAILGUN_MCP_TAGSNão(todas)Tags de produto separadas por vírgula para habilitar. Equivalente a --tags. A flag da CLI tem precedência.

Filtragem por Tags

Você pode limitar quais ferramentas o servidor registra a 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"
}

Descoberta — execute o binário com --list-tags para exibir 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.

Caminhos de Configuração Específicos do Cliente

  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
  • Claude Code: Execute claude mcp add ou edite ~/.claude.json

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"!

Nota: alguns clientes MCP exigem um plano pago para invocar ferramentas que enviam dados. Se o envio falhar silenciosamente, verifique o plano do seu cliente.

Obter 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: [email protected], [email protected].

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.

Desenvolvimento

Para executar a partir do código-fonte, clone o repositório e use node diretamente:

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

Na configuração do seu cliente MCP, substitua o comando npx por:

"command": "node",
"args": ["/path/to/mailgun-mcp-server/src/mailgun-mcp.js"]

Hooks de pré-commit

npm install instala um hook de pré-commit do git (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á marcado por padrão com o tipo de produto send no campo _meta. Se você quiser 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 por 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 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 alcance 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 prevenir abusos — solicitações que excederem 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 poderia enganar o assistente de IA para que ele chame operações que você não pretendia — por exemplo, modificar configurações de rastreamento ou ler membros da lista 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 do webhook. 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 — veja LICENSE para detalhes.

Contribuindo

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