Mailgun

Mailgun MCP Server

Übersicht

Ein Model Context Protocol-Server (MCP) für Mailgun, der KI-Agenten eine praktische, workfloworientierte Schnittstelle zum Versenden von E-Mails, zur Diagnose der Zustellbarkeit und zur Verwaltung von Kontovorgängen bietet.

[!NOTE] Dieser MCP-Server wird lokal auf Ihrem Rechner ausgeführt und kommuniziert über stdio. Mailgun bietet derzeit keine gehostete Version dieses Servers an.

Funktionen

• Messaging — E-Mails versenden, gespeicherte Nachrichten abrufen und erneut versenden
• Domains — Domaindetails anzeigen, DNS-Konfiguration überprüfen und Tracking-Einstellungen verwalten (Klicks, Öffnungen, Abmeldungen)
• Webhooks — Event-Webhooks auflisten, erstellen und aktualisieren
• Routes — Regeln für das Routing eingehender E-Mails anzeigen und aktualisieren
• Mailing Lists — Mailinglisten und ihre Mitglieder erstellen, anzeigen und aktualisieren
• Templates — E-Mail-Vorlagen mit Versionierung erstellen, anzeigen und aktualisieren
• Analytics — Versandmetriken, Nutzungsmetriken und Protokolle abfragen
• Stats — Aggregierte Statistiken nach Domain, Tag, Anbieter, Gerät und Land anzeigen
• Suppressions — Bounces, Abmeldungen, Beschwerden und Allowlist-Einträge anzeigen
• IPs & IP Pools — IP-Zuweisungen und Konfiguration dedizierter IP-Pools anzeigen
• Bounce Classification — Bounce-Typen und Zustellprobleme analysieren
• Validation — Zustellbarkeit und Syntax von E-Mail-Adressen vor dem Versand überprüfen (validate)
• Optimize (Inbox Placement) — Ergebnisse von Inbox-Placement- und Seed-Tests abrufen, um die Zustellbarkeit einzuschätzen (optimize)
• Inspect (Email Preview) — Ergebnisse von E-Mail-Rendering- und Vorschautests für verschiedene Clients abrufen (inspect)
• Account Limits — Benutzerdefinierte monatliche Versandlimits anzeigen

Die obigen Bezeichnungen (validate, optimize, inspect) sind die Produkt-Tags, die für die Tag-Filterung verwendet werden. Alle anderen Funktionen werden unter dem Tag send registriert, der in send.<group> Toolsets unterteilt ist.

[!NOTE] Tools sind auf Lese- und Aktualisierungsvorgänge beschränkt — Löschvorgänge werden nicht bereitgestellt. Dadurch bleibt der mögliche Schaden einer unbeabsichtigten Aktion gering. Siehe Sicherheitsüberlegungen.

Funktionsweise

Der Server basiert auf OpenAPI. Beim Start analysiert er eine gebündelte Mailgun-OpenAPI-Spezifikation und registriert eine kuratierte Allowlist von Endpunkten als MCP-Tools. Dabei wird das Eingabeschema jedes Tools anhand der Spezifikation mit Zod generiert. Jedes Tool ist mit einem Mailgun-Produkt-Tag (send, validate, optimize oder inspect), dem zugehörigen Toolset und der Information gekennzeichnet, ob es ausschließlich Daten liest.

Standardmäßig lädt der Server beim Start alle Tools. Mit --tags dynamic lädt er eine kleine Kernauswahl an Tools sowie drei Tools, mit denen das Modell bei Bedarf weitere Toolsets laden kann. Dadurch bleiben die an das Modell gesendeten Tooldefinitionen kompakt. Die Tag-Filterung lädt stattdessen beim Start eine festgelegte Auswahl an Tools, sodass für einen bestimmten Workflow genau die benötigten Produkte verfügbar gemacht werden können.

Voraussetzungen

• Node.js (v20.12 oder höher)
• Mailgun-Konto und API-Schlüssel

Installation

Der Server wird als @mailgun/mcp-server auf npm veröffentlicht und über stdio ausgeführt. Die meisten Clients können ihn bei Bedarf mit npx starten, sodass keine globale Installation erforderlich ist. Ersetzen Sie in jedem der folgenden Beispiele YOUR-mailgun-api-key durch einen Schlüssel aus Ihren Mailgun-API-Sicherheitseinstellungen.

[!TIP] Wenn Ihr Konto in der EU-Region von Mailgun gehostet wird, fügen Sie "MAILGUN_API_REGION": "eu" zum Block env hinzu (oder verwenden Sie -e MAILGUN_API_REGION=eu in der CLI). Der Standardwert ist us.

Claude Code

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

Führen Sie anschließend in Claude Code /mcp aus, um zu bestätigen, dass der Server mailgun verbunden ist.

Claude Desktop

Öffnen Sie Settings → Developer → Edit Config oder bearbeiten Sie die Datei direkt:

• 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

Öffnen Sie die Befehlspalette und wählen Sie Cursor Settings → MCP → Add new global MCP server. Fügen Sie anschließend Folgendes hinzu:

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

Fügen Sie Folgendes zu Ihrer settings.json hinzu:

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

Fügen Sie Folgendes zu ~/.gemini/settings.json hinzu:

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

Konfiguration

Umgebungsvariablen

Variable	Erforderlich	Standardwert	Beschreibung
MAILGUN_API_KEY	Ja	—	Ihr Mailgun-API-Schlüssel
MAILGUN_API_REGION	Nein	us	API-Region: us oder eu
MAILGUN_API_HOSTNAME	Nein	(aus der Region abgeleitet)	Überschreibt den API-Hostnamen (z. B. api.eu.mailgun.net). Hat Vorrang vor der Region.
MAILGUN_MCP_TAGS	Nein	(alle)	Kommagetrennte Tags oder Toolsets, die geladen werden sollen, oder dynamic, um die Kerntools zu laden und weitere bei Bedarf nachzuladen. Entspricht --tags. Das CLI-Flag hat Vorrang.

CLI-Optionen

Übergeben Sie Flags nach dem Paketnamen in der args Ihres Clients (z. B. ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Flag	Beschreibung
--tags <list>	Kommagetrennte Tags oder Toolsets, die geladen werden sollen (Standard: alle). Gültig sind: all, dynamic, core, send, validate, optimize, inspect und die Toolsets send.<group>.
--list-tags	Gibt alle gültigen Werte für --tags mit Beschreibung aus und beendet das Programm.
--help, -h	Zeigt die Verwendung an und beendet das Programm.

Toolsets bei Bedarf

Mit --tags dynamic (oder MAILGUN_MCP_TAGS=dynamic) startet der Server mit diesen Kerntools:

Tool	Zweck
post-v3-domain-messages	Eine E-Mail versenden
get-v4-domains	Domains auflisten
get-v4-domains-name	Domaindetails und DNS-Einträge
put-v4-domains-name-verify	DNS-Einträge einer Domain erneut überprüfen
get-v3-domains-name-tracking	Tracking-Einstellungen
get_metrics_summary	Zusammenfassung wichtiger Versandmetriken
post-v1-analytics-metrics	Kontometriken abfragen
post-v1-analytics-logs	Ereignisprotokolle abfragen
post-v2-bounce-classification-metrics	Metriken zur Bounce-Klassifizierung
get-v3-domain-bounces	Bounces auflisten
get-v3-domain-bounces-address	Bounce-Eintrag nachschlagen
get-v3-domain-unsubscribes	Abmeldungen auflisten
get-v3-domain-complaints	Beschwerden auflisten
get-v3-domain-templates	Vorlagen auflisten
validate_email	E-Mail-Adresse überprüfen

Jedes Tool gehört zu einem Toolset. Wenn eine Aufgabe es erfordert, lädt das Modell die übrigen Tools eines Toolsets:

Toolset	Tools	Inhalt
send.messages	3	E-Mails versenden; gespeicherte Nachrichten abrufen und erneut versenden
send.domains	8	Domains, DNS-Überprüfung, Versandwarteschlangen, Tracking-Einstellungen
send.webhooks	4	Domain-Webhooks
send.account	8	Konto-IPs, dedizierte IP-Pools, benutzerdefinierte Versandlimits
send.message_tags	8	Nachrichten-Tags, Statistiken nach Tag, Tag-Limits
send.analytics	12	Statistiken und Aggregate, Analytics-Metriken und -Protokolle, Bounce-Klassifizierung
send.suppressions	8	Bounces, Abmeldungen, Beschwerden, Allowlist
send.routes	3	Eingehende Routen
send.lists	8	Mailinglisten und Mitglieder
send.templates	8	Vorlagen und Vorlagenversionen
validate	1	Überprüfung von E-Mail-Adressen
optimize	1	Ergebnisse von Inbox-Placement-Tests
inspect	1	Ergebnisse von E-Mail-Vorschautests

Das Modell lädt Toolsets mithilfe von drei zusätzlichen Tools:

• mailgun_list_toolsets listet alle Toolsets und ihre Tools auf und kennzeichnet, welche geladen sind und welche Daten ändern. Wird ein Toolname angegeben, gibt es stattdessen das Eingabeschema dieses Tools zurück.
• mailgun_enable_toolset lädt ein oder mehrere Toolsets. Anschließend benachrichtigt der Server den Client, dass sich die Toolliste geändert hat (notifications/tools/list_changed), und die neuen Tools erscheinen neben den Kerntools. Die Antwort listet die neuen Tools ohne ihre Eingabeschemas auf; diese werden mit der aktualisierten Toolliste bereitgestellt.
• mailgun_call_tool führt ein schreibgeschütztes Tool anhand seines Namens aus, unabhängig davon, ob sein Toolset geladen ist. Es dient als Ausweichlösung für Clients, die ihre Toolliste nach einer Änderung nicht aktualisieren. Kerntools und Tools, die Daten ändern, werden abgelehnt, sodass diese immer als eigener Toolaufruf ausgeführt werden.

Geladene Toolsets bleiben verfügbar, bis die Verbindung des Clients getrennt wird. Das Laden bei Bedarf setzt einen Client voraus, der seine Toolliste aktualisiert, wenn der Server eine Änderung meldet; Claude Code unterstützt dies. Bei Clients, die das nicht tun, werden neu geladene Tools nicht angezeigt: Schreibgeschützte Tools funktionieren weiterhin über mailgun_call_tool, während Tools, die Daten ändern, den Standardmodus (alle Tools) oder --tags erfordern, zum Beispiel --tags core,send.templates.

Tag-Filterung

Wenn Sie --tags oder MAILGUN_MCP_TAGS auf einen anderen Wert als dynamic setzen, werden beim Start genau die passenden Tools geladen, ohne die Tools zum Laden weiterer Toolsets. Verwenden Sie diese Option, um die dem Modell angezeigten Tools einzugrenzen (zum Beispiel auf Validierungstools für einen Workflow, der keine E-Mails versendet).

Gültige Werte (führen Sie --list-tags aus, um Beschreibungen anzuzeigen):

• all — alle Tools (Standard)
• dynamic — die Kerntools; weitere Toolsets werden bei Bedarf geladen. Verwenden Sie diesen Wert allein; in Kombination mit anderen Werten schlägt der Start fehl.
• core — nur die oben aufgeführten Kerntools
• send, validate, optimize, inspect — alle Tools für das jeweilige Produkt (send umfasst alle send.<group>-Toolsets)
• Eine Toolset-ID wie send.templates

Die Filterung verwendet die ODER-Semantik: Ein Tool wird geladen, wenn es einem beliebigen Wert in der Liste entspricht. Zum Beispiel lädt core,send.templates die Kerntools sowie alle Vorlagentools.

Über das CLI-Flag — übergeben Sie --tags in der args Ihrer MCP-Client-Konfiguration:

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

Über die Umgebungsvariable — setzen Sie MAILGUN_MCP_TAGS (wenn beide angegeben sind, hat das CLI-Flag Vorrang):

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

[!TIP] Führen Sie die Binärdatei mit --list-tags aus, um alle gültigen Werte auszugeben, oder mit --help, um die vollständige Verwendung anzuzeigen. Unbekannte Werte werden beim Start mit einer verständlichen Fehlermeldung abgelehnt.

Beispiel-Prompts

E-Mail senden

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] Einige MCP-Clients benötigen einen kostenpflichtigen Tarif, um Tools aufzurufen, die Daten senden. Wenn das Senden unbemerkt fehlschlägt, überprüfe den Tarif deines Clients.

Versandstatistiken abrufen und visualisieren

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

Vorlagen verwalten

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

Zustellbarkeit untersuchen

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

DNS-Probleme beheben

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

Unterdrückungen überprüfen

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

Routing-Regeln verwalten

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

Mailingliste erstellen

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

Domains vergleichen

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

Engagement nach Region

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

Tracking-Einstellungen überprüfen

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

E-Mail-Adresse validieren

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

Posteingangsplatzierung prüfen (Optimize)

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

E-Mail in der Vorschau anzeigen (Inspect)

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

Entwicklung

Aus dem Quellcode ausführen

Der Server ist in TypeScript geschrieben. Klone das Repository, installiere die Abhängigkeiten, erstelle den Build und führe die Tests aus:

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

npm run build kompiliert src/ nach dist/ und kopiert die gebündelte OpenAPI-Spezifikation. Verweise deinen MCP-Client auf den erstellten Einstiegspunkt statt auf npx (verwende einen absoluten Pfad):

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

Live-Tests während der Bearbeitung

MCP-Server sind langlebige stdio-Prozesse, die nicht automatisch neu geladen werden. Der Ablauf ist daher: bei jedem Speichern neu erstellen und anschließend den Client erneut verbinden, damit die Änderungen übernommen werden.

1. Führe npm run build einmal aus, damit dist/openapi.yaml vorhanden ist.

2. Lass den TypeScript-Compiler laufen, damit dist/ bei jedem Speichern neu erstellt wird:

   npx tsc --watch
   

3. Verweise einen separaten MCP-Client (oder den MCP Inspector weiter unten) auf dist/mailgun-mcp.js. Starte nach einer Änderung die MCP-Client-Sitzung neu, um den neuen Build zu laden.

Mit dem MCP Inspector testen

Mit dem MCP Inspector kannst du Tools ohne vollständigen Client ausprobieren. Erstelle zuerst den Build und starte den Inspector anschließend mit dem erstellten Server:

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

Öffne die Inspector-Benutzeroberfläche, klicke auf Connect und verwende dann List Tools, um zu überprüfen, ob der Server funktioniert. Um ein gefiltertes Toolset zu testen, füge Flags nach dem Serverpfad hinzu:

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

Pre-Commit-Hooks

npm install installiert einen Git-Pre-Commit-Hook (über husky), der oxlint --fix und oxfmt für bereitgestellte TypeScript-/JavaScript-Dateien ausführt und npm run check:versions ausführt. Behebbare Probleme werden automatisch korrigiert und erneut bereitgestellt; Commits mit nicht behebbaren Lint-Fehlern oder Abweichungen bei der Versionssynchronisierung werden abgelehnt. Wenn du bereits vor dieser Änderung einen lokalen Klon hattest, führe npm install einmal aus, um den Hook zu installieren.

Hinweis zum Hinzufügen von Endpunkten

Endpunkte sind in endpointGroups nach Toolset gruppiert. Bei einem einfachen String-Eintrag wird das Produkt-Tag vom Toolset übernommen (send.templates → send), und der Eintrag gilt nur dann als schreibgeschützt, wenn es sich um ein GET handelt. Verwende die Objektform von EndpointEntry, um einen Toolnamen festzulegen, ein Tool als core zu kennzeichnen (wird im dynamischen Modus beim Start geladen) oder ein POST, das nur Daten abfragt, als readOnly: true zu kennzeichnen.

Sicherheitsüberlegungen

Isolierung des API-Schlüssels

Dein Mailgun-API-Schlüssel wird als Umgebungsvariable übergeben und dem KI-Modell selbst niemals offengelegt – er wird ausschließlich vom MCP-Serverprozess zur Authentifizierung von Anfragen verwendet. Der Server protokolliert weder API-Schlüssel noch Anfrageparameter oder Antwortdaten.

Lokale Ausführung

Der Server läuft lokal auf deinem Rechner. Die gesamte Kommunikation mit der Mailgun-API erfolgt über HTTPS mit erzwungener TLS-Zertifikatsprüfung. Abgesehen von der Mailgun-API werden keine Daten an Drittanbieterdienste gesendet.

Berechtigungen des API-Schlüssels

Verwende einen dedizierten Mailgun-API-Schlüssel, dessen Berechtigungen auf die benötigten Vorgänge beschränkt sind. Der Server stellt Lese- und Aktualisierungsvorgänge bereit, aber keine Löschvorgänge. Dadurch wird der mögliche Schaden unbeabsichtigter Aktionen begrenzt.

Ratenbegrenzung

Der Server implementiert keine clientseitige Ratenbegrenzung. Jeder Tool-Aufruf durch die KI wird direkt in eine Mailgun-API-Anfrage umgesetzt. Der Server verlässt sich auf die serverseitigen Ratenbegrenzungen von Mailgun, um Missbrauch zu verhindern – Anfragen, die diese Grenzen überschreiten, geben einen Fehler an den KI-Assistenten zurück.

Prompt-Injection

Wie bei jedem MCP-Server könnte ein manipulierter oder feindseliger Prompt den KI-Assistenten dazu verleiten, Vorgänge aufzurufen, die du nicht beabsichtigt hast – zum Beispiel Tracking-Einstellungen zu ändern oder Mitglieder einer Mailingliste auszulesen. Überprüfe die Bestätigungen für Tool-Aufrufe deines KI-Assistenten, bevor du Aktionen genehmigst, insbesondere bei nicht vertrauenswürdigen Prompts.

Laden von Tools und Genehmigungen

Jedes Tool enthält die MCP-Annotation readOnlyHint, sodass Clients Tools, die nur Daten lesen, von solchen unterscheiden können, die Daten ändern (zum Beispiel bei einer Genehmigungsanfrage). mailgun_list_toolsets und mailgun_call_tool sind schreibgeschützt. mailgun_enable_toolset ändert, welche Tools die Sitzung sieht, und ist daher nicht als schreibgeschützt gekennzeichnet, ändert aber nichts in Mailgun. mailgun_call_tool führt nur schreibgeschützte Tools aus, die nicht zum Kernbestand gehören. Eine Genehmigung kann daher niemals E-Mails versenden oder Kontoeinstellungen ändern. Tools, die Daten ändern, werden immer als eigenständiger Tool-Aufruf ausgeführt.

Das bedarfsgesteuerte Laden von Toolsets schränkt ein, was das Modell sieht; es ist jedoch keine Zugriffskontrolle, da das Modell jedes Toolset laden kann. Um einzuschränken, welche Tools der Server überhaupt bereitstellt, verwende --tags.

Webhook-URLs

Vorgänge zum Erstellen und Aktualisieren von Webhooks akzeptieren beliebige URLs, die über den KI-Assistenten bereitgestellt werden. Der MCP-Server übergibt diese URLs ohne zusätzliche Validierung an die Mailgun-API. Mailgun ist für die Validierung der Webhook-Ziele zuständig. Stelle sicher, dass dein KI-Assistent keine Webhook-URLs auf unbeabsichtigte interne oder vertrauliche Adressen setzt.

Eingabevalidierung

Alle Tool-Parameter werden anhand der Mailgun-OpenAPI-Spezifikation mit Zod-Schemas validiert. Die Validierung hängt jedoch von der Genauigkeit der OpenAPI-Spezifikation ab, und bei einigen Randfallparametern kann eine weniger strenge Validierung zum Einsatz kommen. Die Mailgun-API führt als zusätzliche Schutzmaßnahme eine eigene serverseitige Validierung durch.

Debugging

Der MCP-Server kommuniziert über stdio. Informationen zur Fehlerbehebung findest du im MCP-Debugging-Leitfaden.

Lizenz

Apache 2.0 – Einzelheiten findest du unter LICENSE.

Mitwirken

Beiträge sind willkommen! Du kannst gerne einen Pull Request einreichen oder ein Issue eröffnen.