Email testing with AI agents

MailDev 3.0 ships a built-in Model Context Protocol (MCP) server, so AI agents can search your development inbox, pull verification links, analyze content, and confirm delivery — in natural language. It works with any MCP client, including Claude (Desktop and Code), Cursor, Codex, and Windsurf.

Why it matters: instead of clicking through your inbox to grab a token or confirm an email fired during a test, you just ask. “Get me the verification link from the signup email to user@test.com.” “Did the password reset go out?” Your agent picks the right tools and answers.

⚠️ Development only. The MCP server has full access to email content. Run it in trusted environments, bound to localhost, and never expose it to the internet.

Enable it

There are two transports. The integrated HTTP transport is the simplest — just add the --mcp flag:

maildev --mcp
# SMTP  → localhost:1025
# Web   → http://localhost:1080
# MCP   → http://localhost:1080/mcp

For stdio-based clients (many desktop AI tools), run the standalone server shipped by @maildev/mcp:

maildev-mcp
# connects to a running MailDev over its REST API
# override with --url / MAILDEV_API_URL

Connect your MCP client

Add MailDev to your client's mcpServers config — a project .mcp.json for Claude Code, Cursor, and Codex, or ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop on macOS. Each entry takes an explicit type.

HTTP transport (integrated --mcp)

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

stdio transport (standalone maildev-mcp)

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

Cursor, Codex, Windsurf, Claude Code, and Claude Desktop all accept the same entry shape — check your client's MCP settings for which file to edit. Restart the client after saving.

What your agent can do

The server exposes 5 tools, 3 resources, and 4 ready-made prompts.

Tools

• maildev_search_emails — search by query, from, to, subject, attachments, read state, or time range
• maildev_get_email — full content + attachments for one email
• maildev_get_latest_email — the most recent email(s)
• maildev_delete_email — delete an email by ID
• maildev_get_attachment — download an attachment as base64

Resources

• maildev://emails — the full inbox
• maildev://stats — { emailCount, unreadCount, newestEmail, oldestEmail }
• maildev://email/{id} — a specific email by ID

Prompts

• verify-signup-email — find a signup/verification email and extract its link
• check-password-reset — find a reset email and extract the token/link
• analyze-email-content — pull key info like prices, dates, and links
• monitor-email-delivery — watch for an expected email and verify its contents

Try asking

• “Did I receive any emails in the last 5 minutes?”
• “Get me the verification link from the signup email to user@test.com”
• “Summarize the latest order confirmation email”
• “Did the password reset email go out to user@test.com?”
• “Delete the old test emails”

Full reference, including programmatic setup and troubleshooting, lives in the MCP docs on GitHub.

Get started with MailDev