# Mailgun MCP Server

## Overview

The Mailgun MCP Server lets you manage your Mailgun account through natural language using any AI assistant that supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). 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.

- **GitHub**: [github.com/mailgun/mailgun-mcp-server](https://github.com/mailgun/mailgun-mcp-server)
- **npm**: [@mailgun/mcp-server](https://www.npmjs.com/package/@mailgun/mcp-server)


> **Note:** This MCP server runs locally on your machine. Mailgun does not currently offer a hosted version of this server.


## What Is MCP?

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.

## Capabilities

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 |


## Prerequisites

- **Node.js** v18 or higher
- A **Mailgun API key** (available from your [Mailgun Dashboard](https://app.mailgun.com/settings/api_security))


## Quick Start

### Claude Desktop

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`



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

### Claude Code (CLI)

Run the following command:


```bash
claude mcp add mailgun -- npx -y @mailgun/mcp-server \
  -e MAILGUN_API_KEY=your-api-key-here
```

### Other MCP Clients

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

## Configuration

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

## Example Prompts

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


## Security Considerations

### API key isolation

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.

### Local execution

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.

### API key permissions

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.

### Rate limiting

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.

### Prompt injection

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 URLs

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.

### Input validation

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.

## Troubleshooting

| 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](https://app.mailgun.com/settings/api_security). |
| 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](https://modelcontextprotocol.io/docs/tools/debugging).

## Open Source

The Mailgun MCP Server is open source under the Apache 2.0 license. Contributions are welcome on [GitHub](https://github.com/mailgun/mailgun-mcp-server).