@legendtrading/testmail-mcp

MCP (Model Context Protocol) server for the Legend testmail service (mail.legendcoding.com) — gives any MCP-capable agent (Claude Desktop, Cursor, Cline, …) native tools for temporary email and 2FA/TOTP: create a mailbox, wait for a verification email, read it, send, produce login 2FA codes, and clean up.

It shares the same HTTP client and config as the CLI via @moemail/core, so it talks to the exact same API (authenticated with an X-API-Key).

Tools

| Tool | Description | |------|-------------| | create_email | Create a temporary mailbox (expiry: 1h / 24h / 3d / permanent) | | list_emails | List mailboxes owned by the API key | | list_messages | List messages in a mailbox | | read_message | Read full text/HTML of a message | | wait_for_email | Poll for a new message (bounded, max 90s; returns status: "timeout" to retry) | | send_email | Send from a temporary address (needs send permission) | | delete_email | Delete a mailbox | | delete_message | Delete a single message | | add_totp | Attach a 2FA secret (otpauth:// URI or raw base32) to a mailbox; returns the new totpId and current code | | list_totp | List the 2FA (TOTP) entries on a mailbox, each with its current code | | get_totp_code | Get the current 6-digit TOTP code for an entry (defaults to the mailbox's only entry) | | delete_totp | Remove a 2FA (TOTP) entry from a mailbox |

Configuration

The server reads credentials from environment variables:

• MOEMAIL_API_KEY (required) — your testmail API key (mk_…)
• MOEMAIL_API_URL (optional) — defaults to https://mail.legendcoding.com

Usage

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "legend-testmail": {
      "command": "npx",
      "args": ["-y", "--package=@legendtrading/testmail-mcp", "testmail-mcp"],
      "env": {
        "MOEMAIL_API_KEY": "mk_xxx",
        "MOEMAIL_API_URL": "https://mail.legendcoding.com"
      }
    }
  }
}

⚠️ Use the explicit --package=<pkg> testmail-mcp form, not npx -y @legendtrading/testmail-mcp. npm shipped with Node 24+ mis-infers the command name from a scoped package and fails with testmail-mcp: command not found; separating the package from the binary name avoids this.

Notes

• API keys authenticate against /api/emails*, /api/config*, and the TOTP endpoints — the same surface the CLI uses.
• Authentication, permission, and rate-limit failures from the server are surfaced as descriptive tool errors rather than generic failures.