Mailgun

Servidor MCP do Mailgun

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 capacidade de entrega e gerenciar operações da conta.

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

Recursos

• 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 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 controle de versões
• Análises — Consultar métricas de envio, métricas de uso e registros
• 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 pools de IPs — Visualizar atribuições de IPs e configurações de pools de IPs dedicados
• Classificação de devoluções — Analisar tipos de devolução e problemas de entrega
• Validação — Validar a capacidade de entrega e a sintaxe de endereços de e-mail antes do envio (validate)
• Optimize (posicionamento na caixa de entrada) — Recuperar resultados de testes de posicionamento na caixa de entrada / testes com endereços-semente para avaliar a capacidade de entrega (optimize)
• Inspect (pré-visualização de e-mail) — Recuperar resultados de testes de renderização e pré-visualização de e-mails em diferentes clientes (inspect)
• Limites da conta — Visualizar limites mensais personalizados de envio

Os rótulos acima (validate, optimize, inspect) são as tags de produto usadas pela filtragem por tag. Todos os outros recursos são registrados sob a tag send, dividida em send.<group> conjuntos de ferramentas.

[!NOTE] As ferramentas se limitam a operações de leitura e atualização — nenhuma operação de exclusão é disponibilizada, o que reduz o impacto de uma ação não intencional. Consulte Considerações de segurança.

Como funciona

O servidor é orientado por OpenAPI. Na inicialização, ele analisa uma especificação OpenAPI do Mailgun incluída no pacote e registra uma lista de permissões selecionada 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), o conjunto de ferramentas ao qual pertence e se apenas lê dados.

Por padrão, o servidor carrega todas as ferramentas na inicialização. Com --tags dynamic, ele carrega um pequeno conjunto principal de ferramentas mais três ferramentas que o modelo usa para carregar outros conjuntos de ferramentas sob demanda, mantendo pequenas as definições de ferramentas enviadas ao modelo. A filtragem por tag carrega, em vez disso, um conjunto fixo de ferramentas na inicialização, permitindo que um fluxo de trabalho exponha exatamente os produtos de que precisa.

Pré-requisitos

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

Instalação

O servidor é publicado no npm como @mailgun/mcp-server e é executado por stdio. A maioria dos clientes pode iniciá-lo sob demanda com npx, então não é necessário instalar nada globalmente. 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 valor 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 Settings → Developer → Edit Config 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; em seguida, 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 a ~/.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 (por exemplo, api.eu.mailgun.net). Tem precedência sobre a região.
MAILGUN_MCP_TAGS	Não	(todas)	Tags ou conjuntos de ferramentas separados por vírgulas para carregar, ou dynamic para ferramentas principais com outras carregadas sob demanda. Equivalente a --tags. A opção da CLI tem precedência.

Opções da CLI

Passe as opções após o nome do pacote em args do seu cliente (por exemplo, ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Opção	Descrição
--tags <list>	Tags ou conjuntos de ferramentas separados por vírgulas para carregar (padrão: todos). Valores válidos: all, dynamic, core, send, validate, optimize, inspect e os conjuntos de ferramentas send.<group>.
--list-tags	Exibe todos os valores válidos de --tags com uma descrição e encerra.
--help, -h	Exibe o uso e encerra.

Conjuntos de ferramentas sob demanda

Com --tags dynamic (ou MAILGUN_MCP_TAGS=dynamic), o servidor inicia com estas ferramentas principais:

Ferramenta	Finalidade
post-v3-domain-messages	Enviar um e-mail
get-v4-domains	Listar domínios
get-v4-domains-name	Detalhes do domínio e registros DNS
put-v4-domains-name-verify	Verificar novamente os registros DNS de um domínio
get-v3-domains-name-tracking	Configurações de rastreamento
get_metrics_summary	Resumo das principais métricas de envio
post-v1-analytics-metrics	Consultar métricas da conta
post-v1-analytics-logs	Consultar registros de eventos
post-v2-bounce-classification-metrics	Métricas de classificação de devoluções
get-v3-domain-bounces	Listar devoluções
get-v3-domain-bounces-address	Consultar um registro de devolução
get-v3-domain-unsubscribes	Listar cancelamentos de inscrição
get-v3-domain-complaints	Listar reclamações
get-v3-domain-templates	Listar modelos
validate_email	Validar um endereço de e-mail

Cada ferramenta pertence a um conjunto de ferramentas. O modelo carrega o restante de um conjunto quando uma tarefa precisa dele:

Conjunto de ferramentas	Ferramentas	Conteúdo
send.messages	3	Enviar e-mail; recuperar e reenviar mensagens armazenadas
send.domains	8	Domínios, verificação de DNS, filas de envio, configurações de rastreamento
send.webhooks	4	Webhooks de domínio
send.account	8	IPs da conta, pools de IPs dedicados, limites personalizados de envio
send.message_tags	8	Tags de mensagens, estatísticas por tag, limites de tags
send.analytics	12	Estatísticas e agregações, métricas e registros de análise, classificação de devoluções
send.suppressions	8	Devoluções, cancelamentos de inscrição, reclamações, lista de permissões
send.routes	3	Rotas de entrada
send.lists	8	Listas de e-mails e membros
send.templates	8	Modelos e versões de modelos
validate	1	Validação de endereço de e-mail
optimize	1	Resultados de testes de posicionamento na caixa de entrada
inspect	1	Resultados de testes de pré-visualização de e-mail

O modelo carrega conjuntos de ferramentas usando três ferramentas adicionais:

• mailgun_list_toolsets lista todos os conjuntos de ferramentas e suas ferramentas, indicando quais estão carregadas e quais alteram dados. Se receber o nome de uma ferramenta, retorna o esquema de entrada dessa ferramenta.
• mailgun_enable_toolset carrega um ou mais conjuntos de ferramentas. Em seguida, o servidor notifica o cliente de que a lista de ferramentas foi alterada (notifications/tools/list_changed), e as novas ferramentas aparecem junto às principais. A resposta lista as novas ferramentas sem seus esquemas de entrada, que são fornecidos com a lista de ferramentas atualizada.
• mailgun_call_tool executa uma ferramenta somente de leitura pelo nome, esteja ou não carregado o conjunto de ferramentas correspondente. É uma alternativa para clientes que não atualizam a lista de ferramentas após uma alteração. Recusa ferramentas principais e ferramentas que alteram dados, que sempre são executadas em chamadas próprias.

Os conjuntos de ferramentas carregados permanecem disponíveis até o cliente se desconectar. O carregamento sob demanda requer um cliente que atualize sua lista de ferramentas quando o servidor informa uma alteração; o Claude Code faz isso. Em clientes que não fazem isso, as ferramentas recém-carregadas não aparecem: as ferramentas somente de leitura ainda funcionam por meio de mailgun_call_tool, e as ferramentas que alteram dados exigem o padrão (todas as ferramentas) ou --tags, por exemplo, --tags core,send.templates.

Filtragem por tag

Definir --tags ou MAILGUN_MCP_TAGS com qualquer valor diferente de dynamic carrega exatamente as ferramentas correspondentes na inicialização, sem as ferramentas de carregamento. Use essa opção para restringir as ferramentas exibidas ao modelo (por exemplo, somente ferramentas de validação em um fluxo de trabalho que não envia e-mails).

Valores válidos (execute --list-tags para ver as descrições):

• all — todas as ferramentas (padrão)
• dynamic — as ferramentas principais, com outros conjuntos de ferramentas carregados sob demanda. Use esse valor sozinho; combiná-lo com outros valores causa uma falha na inicialização.
• core — somente as ferramentas principais listadas acima
• send, validate, optimize, inspect — todas as ferramentas desse produto (send abrange todos os conjuntos de ferramentas send.<group>)
• Um ID de conjunto de ferramentas, como send.templates

A filtragem usa semântica OR: uma ferramenta é carregada se corresponder a qualquer valor da lista. Por exemplo, core,send.templates carrega as ferramentas principais e todas as ferramentas de modelos.

Por meio da opção da CLI — passe --tags em 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"
      }
    }
  }
}

Por meio da variável de ambiente — defina MAILGUN_MCP_TAGS (a opção da CLI tem precedência 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 exibir todos os valores válidos ou com --help para ver o uso completo. Valores desconhecidos são rejeitados 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 capacidade de entrega

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 o posicionamento na caixa de entrada (Optimize)

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

Visualizar um e-mail (Inspect)

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. Configure seu cliente MCP para apontar para a entrada compilada 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 em tempo real durante a edição

Os servidores MCP são processos stdio de longa duração que não recarregam automaticamente. Portanto, o ciclo é: recompilar ao salvar e, em seguida, reconectar o cliente para aplicar as alterações.

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. Configure um cliente MCP separado (ou o MCP Inspector, abaixo) para apontar para dist/mailgun-mcp.js. Após uma alteração, reinicie a sessão do cliente MCP para carregar a nova compilação.

Testar com o MCP Inspector

O MCP Inspector permite testar ferramentas sem um cliente completo. Compile primeiro e, em seguida, inicie-o com 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, acrescente sinalizadores 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 de pré-commit do git (via husky) que executa oxlint --fix e oxfmt nos arquivos TypeScript/JavaScript preparados e executa npm run check:versions. Os problemas corrigíveis são corrigidos automaticamente e preparados novamente; commits que introduzem erros de lint não corrigíveis ou incompatibilidades de sincronização de versões são rejeitados. Se você já tinha um clone local antes dessa alteração, execute npm install uma vez para instalar o hook.

Observação sobre a adição de endpoints

Os endpoints são agrupados por conjunto de ferramentas em endpointGroups. Uma entrada de string simples obtém sua tag de produto do conjunto de ferramentas (send.templates → send) e é tratada como somente leitura apenas se for um GET. Use o formato de objeto de EndpointEntry para definir um nome de ferramenta, marcar uma ferramenta como core (carregada na inicialização no modo dinâmico) ou marcar um POST que apenas consulta dados como readOnly: true.

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 próprio modelo de IA — 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 nem dados de resposta.

Execução local

O servidor é executado localmente na sua máquina. Toda a comunicação com a API do Mailgun ocorre por HTTPS, com validação de certificado TLS obrigatória. 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 do Mailgun dedicada, com permissões limitadas apenas às operações necessárias. O servidor expõe operações de leitura e atualização, mas não expõe operações de exclusão, o que limita o impacto de ações não intencionais.

Limitação de taxa

O servidor não implementa limitação de taxa no lado do cliente. Cada chamada de ferramenta feita pela 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 excederem esses limites retornarão um erro ao assistente de IA.

Injeção de prompt

Como em qualquer servidor MCP, um prompt elaborado ou mal-intencionado pode induzir o assistente de IA a chamar operações que você não pretendia — por exemplo, modificar configurações de rastreamento ou ler membros de uma lista de e-mails. Revise as confirmações de chamadas de ferramentas do seu assistente de IA antes de aprovar ações, especialmente em contextos com prompts não confiáveis.

Carregamento e aprovações de ferramentas

Cada ferramenta tem a anotação MCP readOnlyHint, para que os clientes possam distinguir ferramentas que apenas leem dados daquelas que os alteram (por exemplo, ao solicitar aprovação). mailgun_list_toolsets e mailgun_call_tool são somente leitura. mailgun_enable_toolset altera quais ferramentas a sessão vê, portanto não é marcado como somente leitura, mas nunca altera nada no Mailgun. mailgun_call_tool executa apenas ferramentas somente leitura que não fazem parte do conjunto principal, portanto aprová-lo nunca poderá enviar e-mails nem alterar configurações da conta. Ferramentas que alteram dados sempre são executadas como chamadas de ferramenta independentes.

Carregar conjuntos de ferramentas sob demanda reduz o que o modelo vê; isso não é um controle de acesso, pois o modelo pode carregar qualquer conjunto de ferramentas. Para limitar quais ferramentas o servidor expõe, use --tags.

URLs de webhook

As operações de criação e atualização de webhooks aceitam URLs arbitrárias fornecidas pelo assistente de IA. O servidor MCP repassa essas URLs à 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 pretendidos.

Validação de entrada

Todos os parâmetros das ferramentas 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 a uma validação permissiva. A API do Mailgun realiza sua própria validação no lado do servidor como uma camada adicional de proteção.

Depuração

O servidor MCP se comunica por stdio. Consulte o Guia de depuração do MCP para solucionar problemas.

Licença

Apache 2.0 — consulte LICENSE para obter detalhes.

Contribuições

Agradecemos contribuições! Fique à vontade para enviar um Pull Request ou abrir uma Issue.