Mailgun Plugins

Mailgun Plugins helps developers use Mailgun from agent tools like Cursor, Claude Code, and Gemini CLI. Each package connects the agent to @mailgun/mcp-server and adds practical workflows for common Mailgun tasks, including domain setup, delivery diagnostics, suppressions, template QA, and platform operations.

Supported Platforms

Platform	Package	Status	Notes
Cursor	plugins/mailgun-cursor	Full	Marketplace manifest, plugin manifest, MCP config, skills, rules, and commands.
Claude Code / Claude compatible	plugins/mailgun-claude	Supported	Claude marketplace/plugin manifest, MCP config, skills, and commands. Rules are included as guidance files where supported by the client.
Gemini CLI	plugins/mailgun-gemini	Supported	Gemini extension manifest, MCP server config, settings metadata, skills, and TOML commands.

See docs/platform-support.md for the detailed matrix.

How It Works

• shared/ is the canonical source for Mailgun skills, reusable rules, setup docs, example prompts, and examples.
• plugins/mailgun-cursor, plugins/mailgun-claude, and plugins/mailgun-gemini contain platform manifests and generated copies of shared content.
• scripts/sync-shared.mjs copies shared content into each platform package.
• scripts/validate.mjs checks manifests, referenced files, skill frontmatter, MCP version pinning, and required docs.
• CI runs sync drift checks and validation on every push and pull request.

CI and Publication

GitHub Actions is enabled for this repository:

• Validate runs on pushes and pull requests to main.
• Publish Gemini Extension Branch builds plugins/mailgun-gemini into a Gemini extension artifact and publishes it to the gemini-extension branch when Gemini package files change.

MCP Server Compatibility

This repo currently pins plugin MCP startup commands to:

npx -y @mailgun/mcp-server@2.1.0

Required environment:

• MAILGUN_API_KEY: Mailgun private API key.
• MAILGUN_API_REGION: optional MCP server setting, us or eu; the packaged configs omit it and the server defaults to us.
• MAILGUN_MCP_TAGS: optional MCP server setting for a comma separated subset of send, validate, optimize, inspect; the packaged configs omit it and expose all tools.

For EU accounts or scoped tool sets, edit the installed platform MCP config to add MAILGUN_API_REGION or MAILGUN_MCP_TAGS.

Install

Cursor

Install from the Cursor plugin marketplace when published, or add this repository as a marketplace source in Cursor and install mailgun-cursor.

The Cursor package includes:

• Mailgun MCP config at plugins/mailgun-cursor/mcp.json.
• Fifteen skills.
• Safety rules in plugins/mailgun-cursor/rules.
• Commands for domain health, bounces, DNS, suppressions, templates, and reporting across domains.

Claude Code

Add this repository as a Claude plugin marketplace source, then install mailgun-claude.

The Claude package includes a .mcp.json file, the shared Mailgun skills, and Claude compatible commands.

Gemini CLI

Install the generated Gemini extension branch:

gemini extensions install https://github.com/mailgun/mailgun-plugins --ref gemini-extension

The source package is under plugins/mailgun-gemini and includes gemini-extension.json, skills, and TOML commands. Gemini requires gemini-extension.json at the repository root, so GitHub Actions publishes the gemini-extension branch from that package.

Local Development

npm run sync
npm run validate
npm run check:sync
npm run build:gemini

To verify the MCP server tag list from npm:

npm run mcp:tags

To test against a local server checkout, build ../mailgun-mcp-server, then use the local override pattern in shared/docs/setup.md.

Release

1. Update the compatible MCP version in platform MCP configs, docs, and scripts/validate.mjs.
2. Run npm run sync.
3. Run npm run validate, npm run check:sync, and npm run build:gemini.
4. Update changelogs and tag the repo release.
5. Publish or refresh platform marketplace listings. The Gemini extension branch is generated by GitHub Actions.

See docs/release-process.md for details.

Troubleshooting

• Missing API key: set MAILGUN_API_KEY in the platform environment and restart the agent app.
• Wrong region: add MAILGUN_API_REGION=eu to the installed MCP config for EU accounts.
• Too many tools: add MAILGUN_MCP_TAGS to the installed MCP config with a narrower subset.
• Local server testing: build the MCP server first, then point the platform MCP config at dist/mailgun-mcp.js.