The Mailgun MCP Server lets you manage your Mailgun account through natural language using any AI assistant that supports the Model Context Protocol (MCP). Instead of navigating dashboards or writing API calls by hand, you can ask your assistant to send emails, check delivery stats, manage domains, troubleshoot DNS, and more — all conversationally.
Note: This MCP server runs locally on your machine. Mailgun does not currently offer a hosted version of this server.
The Model Context Protocol (MCP) is an open standard that allows AI assistants like Claude, Cursor, and others to securely interact with external tools and services. The Mailgun MCP Server acts as a bridge between your AI assistant and the Mailgun API, exposing 50+ operations as tools the assistant can call on your behalf.
The server provides comprehensive coverage of the Mailgun API across the following areas:
| Category | What You Can Do |
|---|---|
| Sending | Send emails, retrieve stored messages, resend messages |
| Domains | List, inspect, and verify DNS configuration for your sending domains |
| Analytics & Stats | Query delivery metrics, view stats by provider/device/country, generate reports |
| Templates | Create, update, and version email templates |
| Suppressions | Review and manage bounces, unsubscribes, complaints, and allowlists |
| Webhooks | List, create, update, and inspect webhook configurations |
| Routes | Manage inbound email routing rules |
| Mailing Lists | Create and manage mailing lists and their members |
| IPs & IP Pools | View IP assignments, pools, and associated domains |
| Tracking | Configure open, click, and unsubscribe tracking per domain |
- Node.js v18 or higher
- A Mailgun API key (available from your Mailgun Dashboard)
Add the following to your Claude Desktop configuration file:
- 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-api-key-here"
}
}
}
}Run the following command:
claude mcp add mailgun -- npx -y @mailgun/mcp-server \
-e MAILGUN_API_KEY=your-api-key-hereAny client that supports the MCP standard (Cursor, Windsurf, etc.) can use this server. Consult your client's documentation for how to register an MCP server, and provide the same command and environment variables shown above.
| Environment Variable | Required | Default | Description |
|---|---|---|---|
MAILGUN_API_KEY | Yes | — | Your Mailgun API key |
MAILGUN_API_REGION | No | us | API region: us or eu |
If your Mailgun account is in the EU region, add "MAILGUN_API_REGION": "eu" to the env block.
Once configured, you can interact with Mailgun using natural language. Here are some examples to get started:
Sending email
"Send a test email to alice@example.com from noreply@mydomain.com with the subject 'Hello from Mailgun'."
Delivery analytics
"Show me email delivery statistics for the past week across all my domains."
Troubleshooting deliverability
"Check the bounce classification stats and tell me the most common bounce reasons."
DNS verification
"Verify the DNS configuration for mydomain.com and tell me if anything is misconfigured."
Managing suppressions
"Are there any unsubscribes or complaints for mydomain.com in the last 30 days?"
Template management
"Create a welcome email template with a personalized greeting using the variable
{{first_name}}."
Routing rules
"List all my inbound routes and explain what each one does."
Mailing lists
"Create a mailing list called announcements@mydomain.com and add these three members: ..."
Cross-domain comparison
"Compare sending volume and delivery rates across all my domains."
Engagement breakdown
"Break down email engagement by country and device type for mydomain.com."
Your Mailgun API key is passed as an environment variable and is never exposed to the AI model itself — it is only used by the MCP server process to authenticate requests. The server does not log API keys, request parameters, or response data.
The server runs locally on your machine. All communication with the Mailgun API is over HTTPS with TLS certificate validation enforced. No data is sent to third-party services beyond the Mailgun API.
Use a dedicated Mailgun API key with permissions scoped to only the operations you need. The server exposes read and update operations but does not expose any delete operations, which limits the blast radius of unintended actions.
The server does not implement client-side rate limiting. Each tool call from the AI translates directly into a Mailgun API request. The server relies on Mailgun's server-side rate limits to prevent abuse — requests that exceed those limits will return an error to the AI assistant.
As with any MCP server, a crafted or adversarial prompt could trick the AI assistant into calling operations you did not intend — for example, modifying tracking settings or reading mailing list members. Review your AI assistant's tool-call confirmations before approving actions, especially in untrusted prompt contexts.
Webhook create and update operations accept arbitrary URLs provided through the AI assistant. The MCP server passes these URLs to the Mailgun API without additional validation. Mailgun is responsible for validating webhook destinations. Ensure your AI assistant does not set webhook URLs to unintended internal or sensitive addresses.
All tool parameters are validated against the Mailgun OpenAPI specification using Zod schemas. However, validation depends on the accuracy of the OpenAPI spec, and some edge-case parameters may fall back to permissive validation. The Mailgun API performs its own server-side validation as an additional layer of protection.
| Problem | Solution |
|---|---|
| Server not appearing in your client | Ensure Node.js v18+ is installed and the configuration JSON is valid. Restart your MCP client after making changes. |
| Authentication errors | Verify your MAILGUN_API_KEY is correct and active in the Mailgun Dashboard. |
| EU region data not returned | Set MAILGUN_API_REGION to eu in your configuration. |
| Tool calls failing | Check that the domain name used in your prompt matches a verified domain in your Mailgun account. |
For additional debugging guidance, see the MCP Debugging Guide.
The Mailgun MCP Server is open source under the Apache 2.0 license. Contributions are welcome on GitHub.