Mailgun

Serveur MCP Mailgun

Présentation

Un serveur Model Context Protocol (MCP) pour Mailgun qui fournit aux agents d’IA une interface pratique, axée sur les flux de travail, pour envoyer des e-mails, diagnostiquer la délivrabilité et gérer les opérations du compte.

[!NOTE] Ce serveur MCP s’exécute localement sur votre machine et communique via stdio. Mailgun ne propose actuellement pas de version hébergée de ce serveur.

Fonctionnalités

• Messagerie — Envoyer des e-mails, récupérer les messages stockés, renvoyer des messages
• Domaines — Consulter les détails des domaines, vérifier la configuration DNS, gérer les paramètres de suivi (clics, ouvertures, désabonnements)
• Webhooks — Répertorier, créer et mettre à jour les webhooks d’événements
• Routes — Consulter et mettre à jour les règles de routage des e-mails entrants
• Listes de diffusion — Créer, consulter et mettre à jour les listes de diffusion et leurs membres
• Modèles — Créer, consulter et mettre à jour des modèles d’e-mail avec gestion des versions
• Analytique — Interroger les métriques d’envoi, les métriques d’utilisation et les journaux
• Statistiques — Consulter les statistiques agrégées par domaine, étiquette, fournisseur, appareil et pays
• Suppressions — Consulter les rebonds, les désabonnements, les plaintes et les entrées de liste d’autorisation
• Adresses IP et pools d’adresses IP — Consulter les affectations d’adresses IP et la configuration des pools d’adresses IP dédiées
• Classification des rebonds — Analyser les types de rebonds et les problèmes de livraison
• Validation — Valider la délivrabilité et la syntaxe des adresses e-mail avant l’envoi (validate)
• Optimize (placement en boîte de réception) — Récupérer les résultats des tests de placement en boîte de réception / des tests de semence pour évaluer la délivrabilité (optimize)
• Inspect (aperçu des e-mails) — Récupérer les résultats des tests de rendu et d’aperçu des e-mails sur différents clients (inspect)
• Limites du compte — Consulter les limites d’envoi mensuelles personnalisées

Les étiquettes ci-dessus (validate, optimize, inspect) sont les étiquettes de produit utilisées par le filtrage par étiquette. Toutes les autres fonctionnalités sont enregistrées sous l’étiquette send, répartie en send.<group> ensembles d’outils.

[!NOTE] Les outils sont limités aux opérations de lecture et de mise à jour — aucune opération de suppression n’est exposée, ce qui réduit l’impact d’une action involontaire. Consultez les Considérations de sécurité.

Fonctionnement

Le serveur est piloté par OpenAPI. Au démarrage, il analyse une spécification OpenAPI Mailgun intégrée et enregistre une liste d’autorisation sélectionnée de points de terminaison en tant qu’outils MCP, en générant le schéma d’entrée de chaque outil (via Zod) à partir de la spécification. Chaque outil est annoté avec une étiquette de produit Mailgun (send, validate, optimize ou inspect), l’ensemble d’outils auquel il appartient et l’indication qu’il se limite ou non à la lecture des données.

Par défaut, le serveur charge tous les outils au démarrage. Avec --tags dynamic, il charge un petit ensemble d’outils de base ainsi que trois outils que le modèle utilise pour charger d’autres ensembles d’outils à la demande, ce qui réduit la taille des définitions d’outils envoyées au modèle. Le filtrage par étiquette charge plutôt un ensemble fixe d’outils au démarrage, afin qu’un flux de travail donné puisse exposer exactement les produits dont il a besoin.

Prérequis

• Node.js (v20.12 ou version ultérieure)
• Compte Mailgun et clé API

Installation

Le serveur est publié sur npm sous le nom @mailgun/mcp-server et s’exécute via stdio. La plupart des clients peuvent le lancer à la demande avec npx, sans qu’il soit nécessaire de l’installer globalement. Dans chaque extrait ci-dessous, remplacez YOUR-mailgun-api-key par une clé provenant de vos paramètres de sécurité de l’API Mailgun.

[!TIP] Si votre compte est hébergé dans la région UE de Mailgun, ajoutez "MAILGUN_API_REGION": "eu" au bloc env (ou -e MAILGUN_API_REGION=eu sur la CLI). La valeur par défaut est us.

Claude Code

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

Exécutez ensuite /mcp dans Claude Code pour confirmer que le serveur mailgun est connecté.

Claude Desktop

Ouvrez Settings → Developer → Edit Config, ou modifiez directement le fichier :

• 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

Ouvrez la palette de commandes et choisissez Cursor Settings → MCP → Add new global MCP server, puis ajoutez :

{
  "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)

Ajoutez ce qui suit à votre 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

Ajoutez-le à ~/.gemini/settings.json :

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

Configuration

Variables d’environnement

Variable	Obligatoire	Valeur par défaut	Description
MAILGUN_API_KEY	Oui	—	Votre clé API Mailgun
MAILGUN_API_REGION	Non	us	Région de l’API : us ou eu
MAILGUN_API_HOSTNAME	Non	(déduite de la région)	Remplace le nom d’hôte de l’API (par ex. api.eu.mailgun.net). Prioritaire sur la région.
MAILGUN_MCP_TAGS	Non	(tous)	Étiquettes ou ensembles d’outils à charger, séparés par des virgules, ou dynamic pour les outils de base et le chargement d’autres outils à la demande. Équivalent à --tags. L’option CLI est prioritaire.

Options CLI

Passez les options après le nom du package dans le args de votre client (par ex. ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Option	Description
--tags <list>	Étiquettes ou ensembles d’outils à charger, séparés par des virgules (par défaut : tous). Valeurs valides : all, dynamic, core, send, validate, optimize, inspect et les ensembles d’outils send.<group>.
--list-tags	Affiche toutes les valeurs --tags valides avec une description, puis quitte.
--help, -h	Affiche l’aide et quitte.

Ensembles d’outils à la demande

Avec --tags dynamic (ou MAILGUN_MCP_TAGS=dynamic), le serveur démarre avec ces outils de base :

Outil	Fonction
post-v3-domain-messages	Envoyer un e-mail
get-v4-domains	Répertorier les domaines
get-v4-domains-name	Détails du domaine et enregistrements DNS
put-v4-domains-name-verify	Revérifier les enregistrements DNS d’un domaine
get-v3-domains-name-tracking	Paramètres de suivi
get_metrics_summary	Résumé des principales métriques d’envoi
post-v1-analytics-metrics	Interroger les métriques du compte
post-v1-analytics-logs	Interroger les journaux d’événements
post-v2-bounce-classification-metrics	Métriques de classification des rebonds
get-v3-domain-bounces	Répertorier les rebonds
get-v3-domain-bounces-address	Rechercher un enregistrement de rebond
get-v3-domain-unsubscribes	Répertorier les désabonnements
get-v3-domain-complaints	Répertorier les plaintes
get-v3-domain-templates	Répertorier les modèles
validate_email	Valider une adresse e-mail

Chaque outil appartient à un ensemble d’outils. Le modèle charge le reste d’un ensemble lorsqu’une tâche le nécessite :

Ensemble d’outils	Outils	Contenu
send.messages	3	Envoyer des e-mails ; récupérer et renvoyer des messages stockés
send.domains	8	Domaines, vérification DNS, files d’attente d’envoi, paramètres de suivi
send.webhooks	4	Webhooks de domaine
send.account	8	Adresses IP du compte, pools d’adresses IP dédiées, limites d’envoi personnalisées
send.message_tags	8	Étiquettes de message, statistiques par étiquette, limites d’étiquettes
send.analytics	12	Statistiques et agrégats, métriques et journaux analytiques, classification des rebonds
send.suppressions	8	Rebonds, désabonnements, plaintes, liste d’autorisation
send.routes	3	Routes entrantes
send.lists	8	Listes de diffusion et membres
send.templates	8	Modèles et versions de modèles
validate	1	Validation des adresses e-mail
optimize	1	Résultats des tests de placement en boîte de réception
inspect	1	Résultats des tests d’aperçu des e-mails

Le modèle charge les ensembles d’outils à l’aide de trois outils supplémentaires :

• mailgun_list_toolsets répertorie tous les ensembles d’outils et leurs outils, en indiquant lesquels sont chargés et lesquels modifient des données. Si vous lui fournissez un nom d’outil, il renvoie plutôt le schéma d’entrée de cet outil.
• mailgun_enable_toolset charge un ou plusieurs ensembles d’outils. Le serveur informe alors le client que sa liste d’outils a changé (notifications/tools/list_changed), et les nouveaux outils apparaissent aux côtés des outils de base. La réponse répertorie les nouveaux outils sans leurs schémas d’entrée, qui sont fournis avec la liste d’outils mise à jour.
• mailgun_call_tool exécute un outil en lecture seule par son nom, que son ensemble d’outils soit chargé ou non. Il sert de solution de repli pour les clients qui n’actualisent pas leur liste d’outils après une modification. Il refuse les outils de base et ceux qui modifient des données, qui sont donc toujours exécutés dans le cadre de leur propre appel d’outil.

Les ensembles d’outils chargés restent disponibles jusqu’à la déconnexion du client. Le chargement à la demande nécessite un client qui actualise sa liste d’outils lorsque le serveur signale une modification ; Claude Code le fait. Dans les clients qui ne le font pas, les outils nouvellement chargés n’apparaissent pas : les outils en lecture seule restent accessibles via mailgun_call_tool, tandis que les outils qui modifient des données nécessitent la configuration par défaut (tous les outils) ou --tags, par exemple --tags core,send.templates.

Filtrage par étiquette

Définir --tags ou MAILGUN_MCP_TAGS sur une valeur autre que dynamic charge exactement les outils correspondants au démarrage, sans les outils de chargement. Utilisez cette option pour limiter les outils présentés au modèle (par exemple, uniquement les outils de validation pour un flux de travail qui n’envoie pas d’e-mails).

Valeurs valides (exécutez --list-tags pour obtenir leur description) :

• all — tous les outils (valeur par défaut)
• dynamic — les outils de base, avec les autres ensembles d’outils chargés à la demande. Utilisez cette valeur seule ; la combiner avec d’autres valeurs provoque un échec au démarrage.
• core — uniquement les outils de base répertoriés ci-dessus
• send, validate, optimize, inspect — tous les outils de ce produit (send couvre tous les ensembles d’outils send.<group>)
• Un identifiant d’ensemble d’outils tel que send.templates

Le filtrage utilise une logique OU : un outil est chargé s’il correspond à l’une des valeurs de la liste. Par exemple, core,send.templates charge les outils de base ainsi que tous les outils de modèles.

Via l’option CLI — passez --tags dans le args de la configuration de votre client MCP :

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

Via une variable d’environnement — définissez MAILGUN_MCP_TAGS (l’option CLI est prioritaire si les deux sont présentes) :

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

[!TIP] Exécutez le binaire avec --list-tags pour afficher toutes les valeurs valides, ou avec --help pour obtenir l’aide complète. Les valeurs inconnues sont rejetées au démarrage avec un message d’erreur explicite.

Exemples de requêtes

Envoyer un 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] Certains clients MCP nécessitent un forfait payant pour appeler des outils qui envoient des données. Si l’envoi échoue sans message, vérifiez le forfait de votre client.

Récupérer et visualiser les statistiques d’envoi

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

Gérer les modèles

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

Examiner la délivrabilité

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

Résoudre les problèmes DNS

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

Examiner les suppressions

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

Gérer les règles de routage

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

Créer une liste de diffusion

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

Comparer des domaines

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

Engagement par région

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

Examiner les paramètres de suivi

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

Valider une adresse e-mail

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

Vérifier le placement en boîte de réception (Optimize)

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

Prévisualiser un e-mail (Inspect)

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

Développement

Exécuter depuis les sources

Le serveur est écrit en TypeScript. Clonez le dépôt, installez les dépendances, compilez et testez :

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

npm run build compile src/ vers dist/ et copie la spécification OpenAPI intégrée. Configurez votre client MCP pour utiliser le point d’entrée compilé plutôt que npx (utilisez un chemin absolu) :

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

Tester en direct pendant les modifications

Les serveurs MCP sont des processus stdio de longue durée qui ne se rechargent pas automatiquement. Le cycle est donc le suivant : recompiler à chaque enregistrement, puis reconnecter le client pour prendre en compte les modifications.

1. Exécutez npm run build une fois pour que dist/openapi.yaml soit en place.

2. Laissez le compilateur TypeScript s’exécuter pour recompiler dist/ à chaque enregistrement :

   npx tsc --watch
   

3. Configurez un client MCP distinct (ou MCP Inspector, ci-dessous) pour utiliser dist/mailgun-mcp.js. Après une modification, redémarrez la session du client MCP pour charger la nouvelle compilation.

Tester avec MCP Inspector

MCP Inspector vous permet de tester les outils sans client complet. Commencez par compiler, puis lancez-le avec le serveur compilé :

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

Ouvrez l’interface d’Inspector, cliquez sur Connect, puis utilisez List Tools pour vérifier que le serveur fonctionne. Pour tester un ensemble d’outils filtré, ajoutez des options après le chemin du serveur :

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

Hooks de pré-commit

npm install installe un hook git de pré-commit (via husky) qui exécute oxlint --fix et oxfmt sur les fichiers TypeScript/JavaScript indexés, ainsi que npm run check:versions. Les problèmes pouvant être corrigés sont corrigés automatiquement et les fichiers sont de nouveau indexés ; les commits qui introduisent des erreurs de lint impossibles à corriger ou des incohérences de synchronisation des versions sont rejetés. Si vous aviez déjà un clone local avant cette modification, exécutez npm install une fois pour installer le hook.

Remarque sur l’ajout de points de terminaison

Les points de terminaison sont regroupés par ensemble d’outils dans endpointGroups. Une entrée sous forme de chaîne simple reprend l’étiquette de produit de son ensemble d’outils (send.templates → send) et est considérée comme étant en lecture seule uniquement s’il s’agit d’un GET. Utilisez la forme objet de EndpointEntry pour définir un nom d’outil, marquer un outil comme core (chargé au démarrage en mode dynamique) ou marquer un POST qui interroge uniquement les données comme readOnly: true.

Considérations de sécurité

Isolation de la clé API

Votre clé API Mailgun est transmise sous forme de variable d’environnement et n’est jamais exposée au modèle d’IA lui-même : elle est uniquement utilisée par le processus du serveur MCP pour authentifier les requêtes. Le serveur ne consigne ni les clés API, ni les paramètres des requêtes, ni les données des réponses.

Exécution locale

Le serveur s’exécute localement sur votre machine. Toutes les communications avec l’API Mailgun utilisent HTTPS avec validation des certificats TLS. Aucune donnée n’est envoyée à des services tiers autres que l’API Mailgun.

Autorisations de la clé API

Utilisez une clé API Mailgun dédiée dont les autorisations sont limitées aux opérations dont vous avez besoin. Le serveur expose des opérations de lecture et de mise à jour, mais aucune opération de suppression, ce qui limite l’impact d’actions involontaires.

Limitation du débit

Le serveur n’applique pas de limitation du débit côté client. Chaque appel d’outil de l’IA se traduit directement par une requête à l’API Mailgun. Le serveur s’appuie sur les limites de débit côté serveur de Mailgun pour prévenir les abus : les requêtes qui dépassent ces limites renvoient une erreur à l’assistant IA.

Injection de prompt

Comme avec tout serveur MCP, un prompt conçu de manière malveillante ou adversariale pourrait inciter l’assistant IA à appeler des opérations que vous n’aviez pas prévues — par exemple, modifier les paramètres de suivi ou lire les membres d’une liste de diffusion. Examinez les confirmations d’appel d’outil de votre assistant IA avant d’approuver des actions, en particulier dans des contextes de prompts non fiables.

Chargement des outils et approbations

Chaque outil porte l’annotation MCP readOnlyHint, ce qui permet aux clients de distinguer les outils qui lisent uniquement des données de ceux qui les modifient (par exemple, lors d’une demande d’approbation). mailgun_list_toolsets et mailgun_call_tool sont en lecture seule. mailgun_enable_toolset modifie les outils visibles par la session ; il n’est donc pas marqué comme étant en lecture seule, mais il ne modifie rien dans Mailgun. mailgun_call_tool n’exécute que des outils en lecture seule qui ne font pas partie de l’ensemble principal ; son approbation ne peut donc jamais envoyer d’e-mail ni modifier les paramètres du compte. Les outils qui modifient des données sont toujours exécutés dans le cadre de leur propre appel.

Le chargement des ensembles d’outils à la demande réduit ce que le modèle voit ; il ne s’agit pas d’un contrôle d’accès, car le modèle peut charger n’importe quel ensemble d’outils. Pour limiter les outils que le serveur expose, utilisez --tags.

URL de webhook

Les opérations de création et de mise à jour de webhooks acceptent des URL arbitraires fournies par l’intermédiaire de l’assistant IA. Le serveur MCP transmet ces URL à l’API Mailgun sans validation supplémentaire. Mailgun est chargé de valider les destinations des webhooks. Veillez à ce que votre assistant IA ne définisse pas d’URL de webhook pointant vers des adresses internes ou sensibles non souhaitées.

Validation des entrées

Tous les paramètres des outils sont validés à l’aide de schémas Zod conformes à la spécification OpenAPI de Mailgun. Toutefois, la validation dépend de l’exactitude de la spécification OpenAPI, et certains paramètres de cas limites peuvent faire l’objet d’une validation permissive. L’API Mailgun effectue sa propre validation côté serveur comme couche de protection supplémentaire.

Débogage

Le serveur MCP communique via stdio. Consultez le Guide de débogage MCP pour résoudre les problèmes.

Licence

Apache 2.0 — consultez LICENSE pour plus de détails.

Contribution

Vos contributions sont les bienvenues ! N’hésitez pas à soumettre une Pull Request ou à ouvrir une Issue.