MCP server

Enable MailDev's Model Context Protocol server so Claude, Cursor, Codex, and any other MCP client can search your development inbox, pull verification links out of emails, and confirm delivery.

MailDev 3.0 ships a Model Context Protocol server. Your coding agent gets tools for searching and reading the same development inbox you have open in the browser — so "did the signup email arrive, and what was the verification link?" becomes something it can answer itself, mid-task, without you copying anything out of a browser tab.

Why it matters #

Email is the last leg of a lot of flows an agent otherwise handles end to end: signup and confirmation, password reset, magic links, invitations, order receipts. Without access to the inbox, an agent implements the feature and then stops, because the only way to verify it is for a human to go and look. With MCP it closes the loop: trigger the flow, read the message, follow the link, confirm the result.

Enable it #

Add --mcp to how you already start MailDev:

maildev --mcp

The endpoint is at http://localhost:1080/mcp — the same port as the web UI and REST API, so a custom --web port or --base-pathname moves it too.

For desktop AI tools that speak stdio rather than HTTP, there is a standalone server:

maildev-mcp

It talks to a MailDev instance over the REST API, so MailDev itself does not need --mcp for this transport.

Connect your MCP client #

HTTP transport #

For clients that support remote MCP servers over HTTP. Add this to your MCP configuration:

{
  "mcpServers": {
    "maildev": {
      "type": "http",
      "url": "http://localhost:1080/mcp"
    }
  }
}

Each client gets its own session, tracked with an mcp-session-id header, so several tools can talk to one MailDev at the same time.

stdio transport #

For Claude Desktop and anything else that launches a subprocess:

{
  "mcpServers": {
    "maildev": {
      "type": "stdio",
      "command": "maildev-mcp",
      "env": {
        "MAILDEV_API_URL": "http://localhost:1080"
      }
    }
  }
}

If MailDev is not installed globally, use npx:

{
  "mcpServers": {
    "maildev": {
      "command": "npx",
      "args": ["-y", "maildev", "maildev-mcp"]
    }
  }
}

Where the config file lives #

For Claude Code specifically, the step-by-step walkthrough covers setup and a real development loop.

What your agent can do #

Tools #

Responses include a deep link back into the web inbox (http://localhost:1080/#/email/<id>), so when an agent tells you what it found you can open the same message yourself in one click.

Resources #

Prompts #

Pre-built prompts for the flows that come up most:

Try asking #

Once it is connected, these all work as plain requests:

• "Did the signup email for new-user@test.com arrive? What's the verification link?"
• "Show me the most recent email and tell me whether the plain-text version is usable."
• "Search for password reset emails from the last hour."
• "The invoice email has a PDF attached — check that it isn't zero bytes."
• "Clear the inbox, then register a new account and confirm exactly one email was sent."

The last one is the shape worth internalising: clear, act, assert. It gives the agent a deterministic inbox to reason about instead of whatever accumulated during the session.

Troubleshooting #

The client shows no MailDev tools. Check MailDev is running with --mcp, then confirm the endpoint answers:

curl http://localhost:1080/api/healthz

Connection refused on the HTTP transport. The URL must match your actual --web port and --base-pathname. With --base-pathname /maildev the endpoint is http://localhost:1080/maildev/mcp.

maildev-mcp: command not found. The binary comes with the maildev package. Install it globally, or use the npx form above.

Tools appear but every call fails. The stdio server talks to MailDev over HTTP; if MailDev has basic auth enabled, pass --api-key or drop the auth in development.

Full reference #

The complete MCP documentation, including transport internals and the programmatic enablement path, lives in docs/mcp.md in the maildev repository.

Last updated 2026-08-25·Edit this page·View as markdown