migadu

Migadu Claude Code Plugin

Claude Code plugin for Migadu email hosting. Manages domains, mailboxes, aliases, identities, forwardings, and rewrites — and knows how to walk you through the parts that are annoying to get right: DNS setup at your registrar, picking between routing primitives that overlap, configuring an email client, running bulk operations without trashing data.

The plugin bundles the migadu-mcp MCP server (35 tools across the full Migadu API) with five skills that kick in when the tool descriptions alone aren't enough.

Install

Prerequisite: uvx on your PATH.

/plugin marketplace add Michaelzag/migadu-plugin
/plugin install migadu@michaelzag

Then set your credentials in the environment where Claude Code runs:

export [email protected]
export MIGADU_API_KEY=...       # https://admin.migadu.com/account/api/keys
export MIGADU_DOMAIN=example.com # optional — default domain for tools that accept one

Restart Claude Code and the migadu MCP server will show up under /mcp as Connected.

What the skills do

Each skill loads on demand when the topic comes up in conversation. Try asking Claude Code the examples below; the relevant skill will activate automatically.

Skill	What it covers	Try asking
domain-onboarding	Full domain setup: create → DNS records → wait for propagation → diagnostics → activate → usage. Handles the multi-minute external DNS wait.	"Onboard acme.example for email hosting"
dns-configuration	Registrar-specific record setup for Cloudflare, Route 53, Namecheap, GoDaddy, Porkbun, Squarespace, and others. Covers the Cloudflare-proxy gotcha, DKIM line-wrapping, SPF merging.	"I added the DNS records but diagnostics still fail"
routing-decisions	Pick between mailbox, alias, rewrite, and forwarding. They overlap — the wrong choice is hard to migrate away from.	"[email protected] should go to both Alice and Bob"
bulk-safely	Order-of-operations, partial-failure detection, destructive-batch patterns, rollback guidance.	"Create mailboxes for 40 new hires from this CSV"
client-setup	IMAP/SMTP/POP3 settings for Apple Mail, Thunderbird, Outlook, iOS, Android, mutt. Covers Migadu's shared server hostnames, full-email-as-username pattern, and the Outlook SMTP-auth gotcha.	"How do I set up [email protected] in Outlook?"

What the MCP server exposes

35 tools across six resource types — domains, mailboxes, identities, aliases, forwardings, rewrites. Every mutation tool takes a list[dict] of items and returns a bulk-result envelope with per-item success/failure, so "create 40 mailboxes" and "create 1 mailbox" are the same call shape.

Read operations are summarized when they'd blow past a rough token budget, so list_mailboxes on a 500-mailbox domain returns counts plus a sample instead of flooding context.

Ten read-only MCP resource URIs are registered too (domains://, mailbox://{domain}/{local_part}, domain-records://{name}, and so on) for AI clients that prefer addressing data over tool calls.

Full tool inventory lives in the MCP server repo.

Configuration

Variable	Required	Notes
MIGADU_EMAIL	Yes	Admin email on your Migadu account
MIGADU_API_KEY	Yes	From Migadu Admin → API Keys
MIGADU_DOMAIN	No	Default domain for tools that accept an optional domain arg

The plugin's .mcp.json expects these to come through the environment — credentials are never embedded in the plugin itself.

If you manage multiple Migadu domains, leave MIGADU_DOMAIN unset and pass domain explicitly on each tool call. Start with list_domains to see what's available on your account.

Troubleshooting

MCP server shows "Failed to connect" in /mcp. Almost always missing env vars. Verify MIGADU_EMAIL and MIGADU_API_KEY are set in the environment Claude Code inherited. Run echo $MIGADU_EMAIL in the same shell where you launched Claude Code.

"The token is invalid or expired." The MIGADU_EMAIL must match the admin email tied to the API key. API keys are scoped to a specific admin user, not the organization.

uvx: command not found. Install uv. It ships uvx alongside uv.

Skills don't fire when I expect them to. Skills activate based on the conversation content matching their descriptions. If you want to force one, invoke it directly: /migadu:domain-onboarding (or whichever). The plugin's skills are listed under /plugin once installed.