MA
OfficialCommunication

Mailgun MCP Server for AI Email Integration

Enable AI clients to interact with Mailgun using an MCP server for seamless email integration and management.

View on GitHub
Quick Install
npx -y @mailgun/mailgun-mcp-server

Overview

The Mailgun MCP Server implements the Model Context Protocol (MCP) adapter for Mailgun, letting MCP-compatible AI clients interact with your Mailgun account over a local, controlled process. Instead of embedding API keys in prompts or sending credentials to the model, the AI calls the MCP server’s tools to perform Mailgun actions (send mail, query stats, manage templates, etc.). The server runs locally and forwards authenticated requests to the Mailgun API, keeping secret material out of the model’s context.

This approach is useful when you want an AI assistant to operate on real email data or account configuration (for example, generating and sending a campaign, investigating bounce reasons, or updating routing rules) while maintaining clear boundaries for credentials and network access. The server exposes a set of high-level tools mapped to common Mailgun operations so assistant tool calls translate into Mailgun API calls.

Features

  • Messaging: send emails, retrieve stored messages, and resend
  • Domains: view domain details, DNS verification status, and tracking settings
  • Webhooks: list, create, update, delete event webhooks
  • Routes: list and update inbound email routing rules
  • Mailing lists: create/manage lists and list members
  • Templates: create, update, and version templates
  • Analytics & Stats: query sending metrics, aggregate stats by domain/tag/device/country
  • Suppressions: view bounces, unsubscribes, complaints, and allowlist entries
  • IP management: view dedicated IPs and IP pool assignments
  • Bounce classification: analyze bounce types and delivery issues

Installation / Configuration

Prerequisites:

  • Node.js v18+
  • Mailgun account and API key

Quick MCP client configuration (example JSON):

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

Run from source:

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

# In your MCP client config, point to the script:
# "command": "node",
# "args": ["/path/to/mailgun-mcp-server/src/mailgun-mcp.js"]

Environment variables:

VariableRequiredDefaultDescription
MAILGUN_API_KEYYes—Your Mailgun API key (keep secret)
MAILGUN_API_REGIONNousAPI region: us or eu

Client-specific config paths (examples):

  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
  • Claude Code: use claude mcp add or edit ~/.claude.json

Available Tools / Resources

The MCP server exposes a collection of tools that an AI assistant can call. Each tool maps to one or more Mailgun API endpoints:

  • messages.send — send a single message (supports attachments and templates)
  • messages.list / messages.get — retrieve stored messages and details
  • domains.list / domains.get — list domains, DNS verification info, tracking settings
  • webhooks.list / webhooks.create / webhooks.update / webhooks.delete
  • routes.list / routes.update — inspect and update inbound routing rules
  • mailinglists.create / mailinglists.members.add / mailinglists.members.list
  • templates.create / templates.update / templates.list / templates.version
  • stats.query / analytics.usage — aggregate sending metrics over time
  • suppressions.list — view bounces, unsubscribes, complaints
  • ips.list / ip_pools.list — inspect IPs and pools
  • bounce.classify — analyze bounce patterns and common reasons

Each tool returns structured JSON suitable for the assistant to summarize, chart, or act upon.

Use Cases

  • Send transactional or campaign emails through an AI assistant: Example prompt to the assistant: “Send a welcoming onboarding email to [email protected] from [email protected] using the welcome template.”

  • Analyze deliverability: Ask the assistant to fetch bounce classification and provide the top three bounce reasons and suggested mitigations.

  • Verify DNS and domain readiness: Request a domain DNS verification check and a short checklist of required DNS records to fix.

  • Create and iterate templates: Have the assistant create a new template with a personalized greeting and return the template preview URL.

  • Manage inbound routing: List current inbound routes and let the assistant propose a new route to forward specific messages to an internal webhook.

  • Reporting and visualization: Generate weekly charts of delivery, open, and click rates across domains and break down engagement by country and device.

Security & Operational Notes

  • The server runs locally and uses the MAILGUN_API_KEY from your environment; the key is not exposed to the model.
  • All Mailgun API traffic uses HTTPS; validate that your environment enforces TLS.
  • Prefer scoped API keys with minimal permissions for least privilege.
  • The MCP server does not implement client-side rate limiting; Mailgun’s API rate limits still apply.
  • Review any assistant tool calls before approving actions, especially when modifying settings or creating webhooks.

For more details and the latest updates, see the project repository: https://github.com/mailgun/mailgun-mcp-server.

Tags:communication