mcp-mailosaur

MCP server for Mailosaur email testing. Debug Playwright and other e2e test failures involving email with AI agents in VS Code, Claude Desktop, and other MCP clients.

Quick Start

git clone https://github.com/jagypus/mcp-mailosaur.git
cd mcp-mailosaur
npm install --ignore-scripts
npm run build

Then add it to your editor config below.

Configuration

Environment Variables

Variable	Required	Description
MAILOSAUR_API_KEY	Yes	Your Mailosaur API key (get one here)
MAILOSAUR_SERVER_ID	No	Default server ID — saves you from specifying it on every tool call

VS Code (Claude Code / Copilot)

Add to your .vscode/mcp.json:

{
  "servers": {
    "mailosaur": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-mailosaur/dist/index.js"],
      "env": {
        "MAILOSAUR_API_KEY": "your-api-key",
        "MAILOSAUR_SERVER_ID": "your-server-id"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mailosaur": {
      "command": "node",
      "args": ["/path/to/mcp-mailosaur/dist/index.js"],
      "env": {
        "MAILOSAUR_API_KEY": "your-api-key",
        "MAILOSAUR_SERVER_ID": "your-server-id"
      }
    }
  }
}

Available Tools

Messages

Tool	Description
list_messages	List messages in a server with pagination and optional receivedAfter filter
get_message	Get full message details by ID — HTML body, text body, headers, attachments
search_messages	Search for messages by sender, recipient, subject, or body text. Waits for matches with configurable timeout.

Analysis

Tool	Description
check_spam	Run SpamAssassin analysis — score, triggered rules, pass/fail
check_deliverability	Check SPF, DKIM, DMARC, blocklists, and DNS records

Example Debugging Workflows

"My e2e test says the verification email wasn't received"

Ask your AI agent to search for the email:

Search Mailosaur for emails sent to test-user@yourserver.mailosaur.net in the last 10 minutes

"The email is being sent but might be landing in spam"

Check the spam score for message ID xxx

"I want to verify the email content is correct"

Get the full details of the latest message in my Mailosaur inbox

License

MIT