Mailgun MCP Server

offiziell

Interagiere mit der Mailgun-API.

GitHub
56

Dokumentation

Mailgun MCP-Server

MCP

Übersicht

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

Hinweis: Dieser MCP-Server läuft lokal auf Ihrem Rechner. Mailgun bietet derzeit keine gehostete Version dieses Servers an.

Funktionen

  • Messaging — E-Mails versenden, gespeicherte Nachrichten abrufen, Nachrichten erneut senden
  • Domains — Domain-Details anzeigen, DNS-Konfiguration überprüfen, Tracking-Einstellungen verwalten (Klick, Öffnung, Abmeldung)
  • Webhooks — Event-Webhooks auflisten, erstellen, aktualisieren und löschen
  • Routes — Regeln für eingehende E-Mail-Weiterleitung anzeigen und aktualisieren
  • Mailinglisten — Mailinglisten und deren Mitglieder erstellen und verwalten
  • Templates — E-Mail-Vorlagen mit Versionierung erstellen und verwalten
  • 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-Klassifizierung — Bounce-Typen und Zustellungsprobleme analysieren

Voraussetzungen

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

Schnellstart

Konfiguration

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfiguration hinzu:

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

Umgebungsvariablen

VariableErforderlichStandardBeschreibung
MAILGUN_API_KEYJa—Ihr Mailgun-API-Schlüssel
MAILGUN_API_REGIONNeinusAPI-Region: us oder eu
MAILGUN_MCP_TAGSNein(alle)Kommagetrennte Produkt-Tags, die aktiviert werden sollen. Entspricht --tags. CLI-Flag hat Vorrang.

Tag-Filterung

Sie können festlegen, welche Tools der Server registriert, indem Sie einen oder mehrere Mailgun-Produkt-Tags angeben. Dies ist nützlich, um den dem Modell angezeigten Tool-Satz einzugrenzen – beispielsweise, um nur Validierungstools für einen Workflow freizugeben, der keine Sendeberechtigung benötigt.

Gültige Tags: send, validate, optimize, inspect. Wenn nichts angegeben wird, wird jedes Tool registriert (aktueller Standard).

Die Filterung verwendet ODER-Semantik: Ein Tool wird registriert, wenn einer seiner Tags im aktiven Satz enthalten ist.

Via 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"
      }
    }
  }
}

Via Umgebungsvariable — setzen Sie MAILGUN_MCP_TAGS (CLI-Flag gewinnt, wenn beide vorhanden sind):

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

Auffindbarkeit — führen Sie die Binärdatei mit --list-tags aus, um unterstützte Tag-Werte auszugeben, oder mit --help für die vollständige Nutzung. Unbekannte Tags werden beim Start mit einer klaren Fehlermeldung abgelehnt.

Clientspezifische Konfigurationspfade

  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
  • Claude Code: Führen Sie claude mcp add aus oder bearbeiten Sie ~/.claude.json

Beispiel-Prompts

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

Hinweis: Einige MCP-Clients benötigen einen kostenpflichtigen Plan, um Tools aufzurufen, die Daten senden. Wenn das Senden stillschweigend fehlschlägt, überprüfen Sie den Plan Ihres 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-Fehlerbehebung

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

Suppressions ü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.

Eine Mailingliste erstellen

Create a mailing list called announcements@DOMAIN_HERE and add these
members: [email protected], [email protected].

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.

Entwicklung

Um aus dem Quellcode zu starten, klonen Sie das Repository und verwenden Sie node direkt:

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

Ersetzen Sie in Ihrer MCP-Client-Konfiguration den npx-Befehl durch:

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

Pre-Commit-Hooks

npm install installiert einen Git-Pre-Commit-Hook (via Husky), der oxlint --fix und oxfmt für gestagete TypeScript-/JavaScript-Dateien ausführt und npm run check:versions startet. Behebbare Probleme werden automatisch korrigiert und erneut gestaget; Commits, die nicht behebbare Lint-Fehler oder Versionssync-Abweichungen einführen, werden abgelehnt. Wenn Sie bereits einen lokalen Klon vor dieser Änderung hatten, führen Sie npm install einmal aus, um den Hook zu installieren.

Hinweis zum Hinzufügen von Endpunkten

Wenn Sie einen neuen Endpunkt hinzufügen und für seine Definition einen einfachen String verwenden, wird er standardmäßig mit dem Produkttyp send im Feld _meta getaggt. Wenn Sie ihn als ein anderes Produkt taggen möchten, verwenden Sie die Objektversion des Typs EndpointEntry.

Sicherheitsüberlegungen

API-Schlüssel-Isolation

Ihr Mailgun-API-Schlüssel wird als Umgebungsvariable übergeben und niemals dem KI-Modell selbst offengelegt – er wird nur vom MCP-Serverprozess zur Authentifizierung von Anfragen verwendet. Der Server protokolliert keine API-Schlüssel, Anfrageparameter oder Antwortdaten.

Lokale Ausführung

Der Server läuft lokal auf Ihrem Rechner. Die gesamte Kommunikation mit der Mailgun-API erfolgt über HTTPS mit erzwungener TLS-Zertifikatsvalidierung. Es werden keine Daten an Drittanbieterdienste außer der Mailgun-API gesendet.

API-Schlüssel-Berechtigungen

Verwenden Sie einen dedizierten Mailgun-API-Schlüssel mit Berechtigungen, die nur auf die benötigten Operationen beschränkt sind. Der Server stellt Lese- und Aktualisierungsoperationen bereit, aber keine Löschoperationen, was den Explosionsradius unbeabsichtigter Aktionen begrenzt.

Ratenbegrenzung

Der Server implementiert keine clientseitige Ratenbegrenzung. Jeder Tool-Aufruf der KI führt direkt zu einer Mailgun-API-Anfrage. Der Server verlässt sich auf die serverseitigen Ratenlimits von Mailgun, um Missbrauch zu verhindern – Anfragen, die diese Limits überschreiten, geben einen Fehler an den KI-Assistenten zurück.

Prompt-Injection

Wie bei jedem MCP-Server könnte ein speziell gestalteter oder gegnerischer Prompt den KI-Assistenten dazu verleiten, Operationen aufzurufen, die Sie nicht beabsichtigt haben – beispielsweise das Ändern von Tracking-Einstellungen oder das Lesen von Mailinglisten-Mitgliedern. Überprüfen Sie die Tool-Aufrufbestätigungen Ihres KI-Assistenten, bevor Sie Aktionen genehmigen, insbesondere in nicht vertrauenswürdigen Prompt-Kontexten.

Webhook-URLs

Webhook-Erstellungs- und Aktualisierungsoperationen akzeptieren beliebige URLs, die über den KI-Assistenten bereitgestellt werden. Der MCP-Server leitet diese URLs ohne zusätzliche Validierung an die Mailgun-API weiter. Mailgun ist für die Validierung von Webhook-Zielen verantwortlich. Stellen Sie sicher, dass Ihr KI-Assistent keine Webhook-URLs auf unbeabsichtigte interne oder sensible Adressen setzt.

Eingabevalidierung

Alle Tool-Parameter werden anhand der Mailgun-OpenAPI-Spezifikation mit Zod-Schemata validiert. Die Validierung hängt jedoch von der Genauigkeit der OpenAPI-Spezifikation ab, und einige Randfall-Parameter können auf eine permissive Validierung zurückfallen. Die Mailgun-API führt ihre eigene serverseitige Validierung als zusätzliche Schutzebene durch.

Debugging

Der MCP-Server kommuniziert über stdio. Informationen zur Fehlerbehebung finden Sie im MCP Debugging Guide.

Lizenz

Apache 2.0 — siehe LICENSE für Details.

Mitwirken

Wir freuen uns über Beiträge! Bitte reichen Sie gerne einen Pull Request ein oder eröffnen Sie ein Issue.