Mailgun
About
A Model Context Protocol server for Mailgun that gives AI agents a practical, workflow-oriented interface to send email, diagnose deliverability, and manage account operations. It runs locally on your machine—Mailgun does not offer a hosted version.
Details
- Author
- mailgun
- GitHub stars
- 56
- Downloads
- 315
- Categories
- Communication, Automation, API, Developer Tools, Other
Jump to
- Send, retrieve, and resend email messages
- View and manage sending domains and tracking settings
- Create, update, and delete webhooks
- Manage inbound email routing rules
- Create mailing lists and manage their members
- Create and version email templates
- Query sending metrics, usage metrics, and logs
- View aggregate statistics by domain, tag, provider, device, and country
- View bounces, unsubscribes, complaints, and allowlist entries
- Manage IP assignments and dedicated IP pool configuration
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
MailgunCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Add the server entry to your MCP client configuration using the npx command with your Mailgun API key and optional region. Optionally scope the registered tools to one or more product tags (send, validate, optimize, inspect) via the --tags CLI flag or MAILGUN_MCP_TAGS environment variable.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mailgun": {
"mailgun": {
"command": "npx",
"args": [
"-y",
"@mailgun/mcp-server"
],
"env": {
"MAILGUN_API_KEY": "YOUR-mailgun-api-key",
"MAILGUN_API_REGION": "us"
}
}
}
}
}McpServers
{
"mailgun": {
"command": "npx",
"args": [
"-y",
"@mailgun/mcp-server"
],
"env": {
"MAILGUN_API_KEY": "YOUR-mailgun-api-key",
"MAILGUN_API_REGION": "us"
}
}
}[!NOTE] This MCP server runs locally on your machine and communicates over stdio. Mailgun does not currently offer a hosted version of this server.
The parenthetical labels above (validate,optimize,inspect) are the product tags used bytag filtering. Every other capability is registered under thesendtag.
[!NOTE] Tools are limited to read and update operations — no delete operations are exposed, which keeps the blast radius of an unintended action small. SeeSecurity Considerations.
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, orinspect). All matching tools are registered up front — there is no lazy or on demand loading.Tag filteringis applied at startup to scopewhichtools get registered, so a given workflow can expose only the products it needs.
- Node.js (v20.12 or higher)
- Mailgun account and API key
The server is published to npm as@mailgun/mcp-serverand runs over stdio. Most clients can launch it on demand withnpx, so there's nothing to install globally. In each snippet below, replaceYOUR-mailgun-api-keywith a key from yourMailgun API security settings.
[!TIP] If your account is hosted in Mailgun's EU region, add"MAILGUN_API_REGION": "eu"to theenvblock (or-e MAILGUN_API_REGION=euon the CLI). It defaults tous.
claude mcp add mailgun -e MAILGUN_API_KEY=YOUR-mailgun-api-key -- npx -y @mailgun/mcp-server
Then run/mcpin Claude Code to confirm themailgunserver is connected.
OpenSettings → Developer → Edit Config, or edit the file directly:
- 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" } } } }
Open the command palette and chooseCursor Settings → MCP → Add new global MCP server, then add:
{ "mcpServers": { "mailgun": { "command": "npx", "args": ["-y", "@mailgun/mcp-server"], "env": { "MAILGUN_API_KEY": "YOUR-mailgun-api-key" } } } }
codex mcp add mailgun \ --env MAILGUN_API_KEY=YOUR-mailgun-api-key \ -- npx -y @mailgun/mcp-server
Add the following to yoursettings.json:
{ "mcp": { "servers": { "mailgun": { "command": "npx", "args": ["-y", "@mailgun/mcp-server"], "env": { "MAILGUN_API_KEY": "YOUR-mailgun-api-key" } } } } }
{ "mcpServers": { "mailgun": { "command": "npx", "args": ["-y", "@mailgun/mcp-server"], "env": { "MAILGUN_API_KEY": "YOUR-mailgun-api-key" } } } }
{ "mcpServers": { "mailgun": { "command": "npx", "args": ["-y", "@mailgun/mcp-server"], "env": { "MAILGUN_API_KEY": "YOUR-mailgun-api-key" } } } }
Pass flags after the package name in your client'sargs(e.g.["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).
You can scope which tools the server registers to one or more Mailgun product tags. This is useful for narrowing the toolset shown to the model — for example, only exposing validation tools to a workflow that doesn't need send capabilities.
Valid tags:send,validate,optimize,inspect. When unspecified, every tool is registered (today's default).
Filtering usesOR semantics: a tool is registered if any of its tags appears in the active set.
Via CLI flag— pass--tagsin your MCP client config'sargs:
{ "mcpServers": { "mailgun": { "command": "npx", "args": ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"], "env": { "MAILGUN_API_KEY": "YOUR-mailgun-api-key" } } } }
Via environment variable— setMAILGUN_MCP_TAGS(CLI flag wins if both are present):
"env": { "MAILGUN_API_KEY": "YOUR-mailgun-api-key", "MAILGUN_MCP_TAGS": "validate,inspect" }
[!TIP] Run the binary with--list-tagsto print supported tag values, or--helpfor full usage. Unknown tags are rejected at startup with a clear error message.
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] Some MCP clients require a paid plan to invoke tools that send data. If sending fails silently, check your client's plan.
Would you be able to make a chart with email delivery statistics for the past week?
Create a welcome email template for new signups on my domain DOMAIN_HERE. Include a personalized greeting and a call-to-action button.
Can you check the bounce classification stats for my account and tell me what the most common bounce reasons are?
Check the DNS verification status for my domain DOMAIN_HERE and tell me if anything needs fixing.
List all my inbound routes and explain what each one does.
Create a mailing list called announcements@DOMAIN_HERE and add these members: alice@example.com, bob@example.com.
Compare my sending volume and delivery rates across all my domains for the past month.
Break down my email engagement by country and device for DOMAIN_HERE.
List all my domains and show which ones have tracking enabled for clicks and opens.
Validate the email address EMAIL_HERE and tell me whether it's safe to send to.
Pull the inbox placement results for seed test RESULT_ID_HERE and summarize where my message landed (inbox, spam, or missing) by provider.
Get the email preview results for test TEST_ID_HERE and tell me if the email renders correctly across clients.
The server is written in TypeScript. Clone, install, build, and test:
git clone https://github.com/mailgun/mailgun-mcp-server.git cd mailgun-mcp-server npm install npm run build npm test
npm run buildcompilessrc/todist/and copies the bundled OpenAPI spec. Point your MCP client at the built entry instead ofnpx(use an absolute path):
{ "mcpServers": { "mailgun": { "command": "node", "args": ["/absolute/path/to/mailgun-mcp-server/dist/mailgun-mcp.js"], "env": { "MAILGUN_API_KEY": "YOUR-mailgun-api-key" } } } }
MCP servers are long-lived stdio processes that don't hot-reload, so the loop is: rebuild on save, then reconnect the client to pick up changes.
-
Runnpm run buildonce sodist/openapi.yamlis in place.
Keep the TypeScript compiler running to rebuilddist/on every save:
Point a separate MCP client (or MCP Inspector, below) atdist/mailgun-mcp.js. After a change, restart the MCP client session to load the new build.
npm run build MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js
Open the Inspector UI, clickConnect, then useList Toolsto verify the server is working. To test a filtered toolset, append flags after the server path:
MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js --tags validate,inspect
npm installinstalls a git pre-commit hook (via husky) that runsoxlint --fixandoxfmton staged TypeScript/JavaScript files and runsnpm run check:versions. Fixable issues are auto-fixed and re-staged; commits that introduce unfixable lint errors or version-sync mismatches are rejected. If you already had a local clone before this change, runnpm installonce to install the hook.
When adding a new endpoint if you use a plain string for it's definition it will default to being tagged with thesendproduct type in the_metafield. If you would like to tag it as a different product use the object version of theEndpointEntrytype.
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.
The MCP server communicates over stdio. Refer to theMCP Debugging Guidefor troubleshooting.
We welcome contributions! Please feel free to submit aPull Requestor open anIssue.
Enables seamless integration with communication platform that allows you to reach your customers globally across any channel.
Send emails directly from your editor using the Resend API.
Sendmux is an email inbox API and email API for AI agents.
Self-hosted email and SMS platform for AI agents — each agent gets a real email address, phone number, inbox, and API key.
Give your AI agent its own email address — instant bot inboxes via API, no human setup required.
Sends emails using the Resend API. Requires a Resend API key.
Context Intelligence API that returns structured, cited answers from email threads, attachments, and Google Drive docs in one API call.
An MCP server for sending emails via the Postmark service, configured through environment variables.
Transactional SendGrid MCP: preflight send, templates, delivery diagnostics, account/console settings, optional Event Webhook receiver. Self-hosted binary, BYOK.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
