mailgun/mailgun-mcp-server

Overview
A Model Context Protocol (MCP) server for Mailgun that gives AI agents a practical, workflow-oriented interface to send email, diagnose deliverability, and manage account operations.
> [!NOTE]
> This MCP server runs locally on your machine and communicates over stdio. Mailgun does not currently offer a hosted version of this server.
Capabilities
- **Messaging** — Send emails, retrieve stored messages, resend messages
- **Domains** — View domain details, verify DNS configuration, manage tracking settings (click, open, unsubscribe)
- **Webhooks** — List, create, and update event webhooks
- **Routes** — View and update inbound email routing rules
- **Mailing Lists** — Create, view, and update mailing lists and their members
- **Templates** — Create, view, and update email templates with versioning
- **Analytics** — Query sending metrics, usage metrics, and logs
- **Stats** — View aggregate statistics by domain, tag, provider, device, and country
- **Suppressions** — View bounces, unsubscribes, complaints, and allowlist entries
- **IPs & IP Pools** — View IP assignments and dedicated IP pool configuration
- **Bounce Classification** — Analyze bounce types and delivery issues
- **Validation** — Validate email address deliverability and syntax before sending (validate)
- **Optimize (Inbox Placement)** — Retrieve inbox placement / seed test results to gauge deliverability (optimize)
- **Inspect (Email Preview)** — Retrieve email rendering and preview test results across clients (inspect)
- **Account Limits** — View custom monthly sending limits
The parenthetical labels above (validate, optimize, inspect) are the product tags used by tag filtering. Every other capability is registered under the send tag.
> [!NOTE]
> Tools are limited to read and update operations — no delete operations are exposed, which keeps the blast radius of an unintended action small. See Security Considerations.
How it works
The server is OpenAPI driven. At startup it parses a bundled Mailgun OpenAPI spec and registers a curated allowlist of endpoints as MCP tools, generating each tool's input schema (via Zod) from the spec. Every tool is annotated with a Mailgun product tag (send, validate, optimize, or inspect). All matching tools are registered up front — there is no lazy or on demand loading. Tag filtering is applied at startup to scope *which* tools get registered, so a given workflow can expose only the products it needs.
Prerequisites
- Node.js (v20.12 or higher)
- Mailgun account and API key
Installation
The server is published to npm as @mailgun/mcp-server and runs over stdio. Most clients can launch it on demand with npx, so there's nothing to install globally. In each snippet below, replace YOUR-mailgun-api-key with a key from your Mailgun API security settings.
> [!TIP]
> If your account is hosted in Mailgun's EU region, add "MAILGUN_API_REGION": "eu" to the env block (or -e MAILGUN_API_REGION=eu on the CLI). It defaults to us.
Claude Code
Then run /mcp in Claude Code to confirm the **mailgun** server is connected.
Claude Desktop
Open **Settings → Developer → Edit Config**, or edit the file directly:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json
Cursor
Open the command palette and choose **Cursor Settings → MCP → Add new global MCP server**, then add:
Codex
VS Code (GitHub Copilot)
Add the following to your settings.json:
Windsurf
Gemini CLI
Add to ~/.gemini/settings.json:
Configuration
Environment variables
| Variable | Required | Default | Description |
| ---------------------- | -------- | -------------------- | ------------------------------------------------------------------------------------------- |