Mailsac MCP server

The official Model Context Protocol server for Mailsac. It gives AI coding agents (Claude Code, Cursor, VS Code, Claude Desktop and other MCP clients) disposable test inboxes, so an agent can check the email your application sends: sign-up confirmations, password resets, magic links and one-time codes.

A typical conversation:

Sign up for a new account on http://localhost:3000 and confirm it by email.

The agent creates a unique address with Mailsac, fills in your sign-up form, waits for the confirmation email, follows the link, and tells you what it found. The same tools help it write and debug end-to-end tests for those flows.

Tools

| Tool | What it does | Mailsac operations | |---|---|---| | create_test_address | A new unique address, e.g. [email protected]. Nothing to create first. | none | | wait_for_email | Waits until a matching email arrives (optionally by subject, sender or time), then returns the subject, text, links, the most likely confirm/reset/login link (actionLink) and candidate one-time codes. | 1 per check, plus 1 to read | | list_emails | Emails stored at an address, newest first. | 1 | | read_email | One email as text (with links and codes), HTML, raw MIME or headers. | 1 | | delete_emails | Delete one email, or all emails at an address. | 1 per call or message | | list_domains | Your account's private domains, to use with create_test_address. | 1 |

Set up

You need a Mailsac API key. The free plan works: create an account, then create a key.

Claude Code

claude mcp add mailsac -e MAILSAC_API_KEY=your-key -- npx -y @mailsac/mcp

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) and other clients that use the same format:

{
  "mcpServers": {
    "mailsac": {
      "command": "npx",
      "args": ["-y", "@mailsac/mcp"],
      "env": { "MAILSAC_API_KEY": "your-key" }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "mailsac": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mailsac/mcp"],
      "env": { "MAILSAC_API_KEY": "your-key" }
    }
  }
}

Settings

| Variable | Default | Purpose | |---|---|---| | MAILSAC_API_KEY | (required) | Your Mailsac API key | | MAILSAC_DOMAIN | mailsac.com | Domain for new test addresses. Set it to your private domain. | | MAILSAC_API_URL | https://mailsac.com/api | API base URL |

Public inboxes and private domains

Addresses at @mailsac.com are public: anyone who guesses an address can read its mail. They are ideal for made-up test data and need no setup. For anything real, such as a staging environment that sends real customer names, use a private domain: your own subdomain (for example test.example.com) or a zero-setup yourteam.msdc.co subdomain from the domains page. Set MAILSAC_DOMAIN and every new address uses it.

Operations and limits

Each API call uses one Mailsac operation. wait_for_email checks every 3 seconds by default, so a message that arrives within a few seconds costs about 2 to 5 operations. The free plan includes 1,500 operations a month; paid plans start at 25,000.

How Mailsac knows this is the MCP server

Requests from this server carry Mailsac-Client: mcp and a mailsac-mcp/<version> user agent. Mailsac counts these in aggregate to see how many people use Mailsac through AI agents. Email content is never part of that count.

Develop

npm install
npm test          # builds, then runs the tests with a fake Mailsac API
MAILSAC_API_KEY=your-key node dist/index.js   # runs the server over stdio

License

MIT