Mailgun

Mailgun MCP Server

Ü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.

[!NOTE] Dieser MCP-Server läuft lokal auf Ihrem Rechner und kommuniziert über stdio. 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 (Klicks, Öffnungen, Abmeldungen)
• Webhooks — Event-Webhooks auflisten, erstellen und aktualisieren
• Routes — Regeln für eingehende E-Mail-Weiterleitung anzeigen und aktualisieren
• Mailing Lists — Mailinglisten und deren 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 Zustellungsprobleme analysieren
• Validation — Zustellbarkeit und Syntax von E-Mail-Adressen vor dem Versand validieren (validate)
• Optimize (Inbox Placement) — Ergebnisse von Posteingangsplatzierungs-/Seed-Tests abrufen, um die Zustellbarkeit einzuschätzen (optimize)
• Inspect (Email Preview) — Ergebnisse der E-Mail-Darstellung und Vorschautests über verschiedene Clients hinweg abrufen (inspect)
• Account Limits — Individuelle monatliche Versandlimits anzeigen

Die oben in Klammern gesetzten Bezeichnungen (validate, optimize, inspect) sind die Produkt-Tags, die von der Tag-Filterung verwendet werden. Alle anderen Funktionen sind unter dem send-Tag registriert.

[!NOTE] Die Tools sind auf Lese- und Aktualisierungsoperationen beschränkt — es werden keine Löschoperationen bereitgestellt, was den Wirkungsradius einer unbeabsichtigten Aktion gering hält. Siehe Sicherheitshinweise.

Funktionsweise

Der Server ist OpenAPI-gesteuert. Beim Start analysiert er eine gebündelte Mailgun-OpenAPI-Spezifikation und registriert eine kuratierte Allowlist von Endpunkten als MCP-Tools, wobei das Eingabeschema jedes Tools (via Zod) aus der Spezifikation generiert wird. Jedes Tool ist mit einem Mailgun-Produkt-Tag versehen (send, validate, optimize oder inspect). Alle passenden Tools werden im Voraus registriert — es gibt kein Lazy- oder On-Demand-Laden. Die Tag-Filterung wird beim Start angewendet, um den Umfang der zu registrierenden Tools festzulegen, sodass ein bestimmter Workflow nur die benötigten Produkte bereitstellen kann.

Voraussetzungen

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

Installation

Der Server wird auf npm als @mailgun/mcp-server veröffentlicht und läuft über stdio. Die meisten Clients können ihn bei Bedarf mit npx starten, sodass keine globale Installation erforderlich ist. Ersetzen Sie in jedem der folgenden Ausschnitte 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 env-Block hinzu (oder -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 dann /mcp in Claude Code aus, um zu bestätigen, dass der mailgun-Server verbunden ist.

Claude Desktop

Öffnen Sie Einstellungen → Entwickler → Konfiguration bearbeiten 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-Einstellungen → MCP → Neuen globalen MCP-Server hinzufügen und fügen Sie dann 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

Zu ~/.gemini/settings.json hinzufügen:

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

Konfiguration

Umgebungsvariablen

Variable	Erforderlich	Standard	Beschreibung
MAILGUN_API_KEY	Ja	—	Ihr Mailgun API-Schlüssel
MAILGUN_API_REGION	Nein	us	API-Region: us oder eu
MAILGUN_API_HOSTNAME	Nein	(von Region abgeleitet)	Überschreibt den API-Hostnamen (z. B. api.eu.mailgun.net). Hat Vorrang vor der Region.
MAILGUN_MCP_TAGS	Nein	(alle)	Kommagetrennte Liste der zu aktivierenden Produkt-Tags. 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 Liste der zu aktivierenden Produkt-Tags (Standard: alle). Gültig: send, validate, optimize, inspect.
--list-tags	Gibt die gültigen Tag-Werte aus und beendet das Programm.
--help, -h	Zeigt die Verwendung an und beendet das Programm.

Tag-Filterung

Sie können den Umfang der vom Server registrierten Tools auf ein oder mehrere Mailgun-Produkt-Tags beschränken. Dies ist nützlich, um den dem Modell angezeigten Tool-Satz einzugrenzen – beispielsweise, um nur Validierungstools für einen Workflow bereitzustellen, der keine Versandfunktionen benötigt.

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

Die Filterung verwendet ODER-Semantik: Ein Tool wird registriert, wenn eines 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 (das CLI-Flag hat Vorrang, wenn beide vorhanden sind):

"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 unterstützte Tag-Werte auszugeben, oder mit --help für die vollständige Verwendung. Unbekannte Tags werden beim Start mit einer klaren Fehlermeldung abgelehnt.

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

[!NOTE] Einige MCP-Clients erfordern 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: 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.

Eine 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.

Eine E-Mail-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. Klonen, installieren, bauen und testen:

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. Richten Sie Ihren MCP-Client auf den gebauten Einstiegspunkt anstelle von npx (verwenden Sie 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 kein Hot-Reloading unterstützen. Der Ablauf ist daher: Beim Speichern neu bauen, dann den Client erneut verbinden, um die Änderungen zu übernehmen.

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

2. Lassen Sie den TypeScript-Compiler laufen, um dist/ bei jedem Speichern neu zu bauen:

   npx tsc --watch
   

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

Testen mit dem MCP Inspector

Der MCP Inspector ermöglicht es Ihnen, Tools ohne vollständigen Client zu testen. Bauen Sie zuerst und starten Sie ihn dann mit dem gebauten Server:

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

Öffnen Sie die Inspector-Benutzeroberfläche, klicken Sie auf Verbinden und verwenden Sie dann Tools auflisten, um zu überprüfen, ob der Server funktioniert. Um einen gefilterten Tool-Satz zu testen, hängen Sie Flags nach dem Server-Pfad an:

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 (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.

Sicherheitshinweise

API-Schlüssel-Isolation

Ihr Mailgun-API-Schlüssel wird als Umgebungsvariable übergeben und ist niemals dem KI-Modell selbst zugänglich – 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 von Ihnen benötigten Operationen beschränkt sind. Der Server stellt Lese- und Aktualisierungsoperationen bereit, aber keine Löschoperationen, was den Wirkungsradius unbeabsichtigter Aktionen begrenzt.

Ratenbegrenzung

Der Server implementiert keine clientseitige Ratenbegrenzung. Jeder Tool-Aufruf der KI wird direkt in eine Mailgun-API-Anfrage übersetzt. 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 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 Auslesen 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, vom KI-Assistenten bereitgestellte URLs. 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 freizügigere 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.