TempMail MCP

English | 中文

A Model Context Protocol server that provides temporary email services for AI agents, enabling closed-loop verification of email-based registration flows.

For AI agents: Read the AI Guide for tool-by-tool instructions, decision trees, and workflow patterns.
AI 代理指南： 阅读 中文指南 获取工具使用说明、决策树和工作流模式。

Features

• Multi-provider aggregation — 6 temp-mail providers behind one unified interface

• No API key required for 4 out of 6 providers (Mail.tm, Guerrilla Mail, 1secmail, Catchmail)

• Auto-registration — automatically obtain MailDrop and mail.cx API keys via pure HTTP API calls (no browser needed)

• Verification code extraction — automatically extracts OTP/verification codes from incoming emails in 6 languages (English, Chinese, Japanese, Russian, French, German)

• Wait-for-email — blocking/long-poll until a matching email arrives

• Session management — tracks created mailboxes in-memory for the MCP session

• Zero heavy dependencies — no Puppeteer, no Playwright, just Node.js built-in modules

Related MCP server: agent-inbox

Supported Providers

Tip: Use the auto_register tool to automatically obtain MailDrop and mail.cx API keys — no manual signup needed.

Installation

From npm

npm install -g @bencibro/tempmail-mcp

Or use directly with npx (no install needed):

npx @bencibro/tempmail-mcp

From source

git clone https://github.com/Bencibr/tempmailmcp.git
cd tempmailmcp
npm install
npm run build

Configuration

Environment Variables

Claude Desktop / Cursor / MCP Client Config

Option A: Using npx (recommended, no install needed)

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "tempmail": {
      "command": "npx",
      "args": ["-y", "@bencibro/tempmail-mcp"],
      "env": {
        "MAILDROP_API_KEY": "your-maildrop-api-key",
        "MAILCX_API_TOKEN": "your-mailcx-api-token"
      }
    }
  }
}

If you only need the free providers (no API keys), simply omit the env block:

{
  "mcpServers": {
    "tempmail": {
      "command": "npx",
      "args": ["-y", "@bencibro/tempmail-mcp"]
    }
  }
}

Option B: Global install

npm install -g @bencibro/tempmail-mcp

Then use tempmail-mcp as the command:

{
  "mcpServers": {
    "tempmail": {
      "command": "tempmail-mcp",
      "env": {
        "MAILDROP_API_KEY": "your-maildrop-api-key",
        "MAILCX_API_TOKEN": "your-mailcx-api-token"
      }
    }
  }
}

Don't have an API key? Use the auto_register tool to automatically obtain a free MailDrop or mail.cx API key — no browser needed, pure HTTP API calls. See Auto-Register below.

Available Tools

list_providers

List all available temporary email providers and their capabilities.

get_domains

Get the list of available email domains for a given provider.

• provider (optional, default "mail.tm"): Provider name.

create_mailbox

Create a new temporary email mailbox.

• provider (optional, default "mail.tm"): Provider name.

• username (optional): Preferred username (local part).

• domain (optional): Preferred domain.

get_messages

Get the list of received emails for a mailbox.

• address: The temporary email address.

get_message

Get the full content of a specific email.

• address: The temporary email address.

• messageId: The message ID (from get_messages).

wait_for_email

Block until a matching email arrives. Returns the first matching message.

• address: The temporary email address.

• subjectContains (optional): Filter by subject substring.

• fromContains (optional): Filter by sender substring.

• timeoutMs (optional, default 60000): Timeout in ms.

• pollIntervalMs (optional, default 3000): Poll interval in ms.

get_verification_code

Wait for a verification email and automatically extract the verification code. Supports verification emails in 6 languages: English, Chinese (简体/繁体), Japanese, Russian, French, and German.

Uses a multi-strategy extraction algorithm:

1. Contextual matching — looks for language-specific keywords (e.g. code, 验证码, 認証, код, vérification, Bestätigung) near a code-like token

2. Standalone digit codes — falls back to pure-digit codes (6-digit prioritized), filtering out years and false positives

3. Alphanumeric codes — last-resort fallback to uppercase alphanumeric tokens, filtering out pure-letter words

• address: The temporary email address.

• subjectContains (optional): Filter (e.g. "verification", "confirm", "code", "验证").

• fromContains (optional): Filter by sender.

• timeoutMs (optional, default 60000): Timeout in ms.

list_mailboxes

List all temporary mailboxes created in this session.

delete_mailbox

Delete a temporary mailbox and all its messages.

• address: The temporary email address.

auto_register

Automatically register an account and obtain an API key/token for a provider. Pure HTTP API — no browser, no Puppeteer.

maildrop

Uses RSA key generation + HTTP API:

1. Generates an RSA 2048 keypair (Node.js crypto module)

2. POST /api/register.php with the public key

3. Signs timestamp-username to create a passcode

4. POST /api/login.php to authenticate

5. POST /api/account/keys.php to create an API key (md_...)

mail.cx

Uses magic-link sign-in flow:

1. Creates a temp mailbox via mail.tm (no API key needed)

2. POST /v1/auth/magic-link/request to send a magic link to the temp email

3. Polls mail.tm for the magic link email

4. POST /v1/auth/magic-link/verify with the token — returns the API token directly (tm_live_...)

Parameters:

• provider (required): "maildrop" or "mail.cx"

• tokenName (optional, default "tempmail-mcp"): Name for the token (mail.cx only).

• username (optional): Username for the account (maildrop only).

• timeoutMs (optional, default 120000): Overall timeout in milliseconds.

Returns the API key/token and automatically registers the provider in the current session. To make it permanent, set the corresponding environment variable (MAILDROP_API_KEY or MAILCX_API_TOKEN).

Usage Examples

Auto-Register to Get a Free API Key

MailDrop (fast, ~2 seconds):

1. auto_register (provider: "maildrop")
   → { apiKey: "md_...", email: "tmp_xxx@maildrop.cc", ... }

2. [Set MAILDROP_API_KEY=md_... in your MCP config]

3. list_providers
   → Now includes "maildrop" in the provider list!

mail.cx (~15-30 seconds, waits for email):

1. auto_register (provider: "mail.cx")
   → { apiKey: "tm_live_...", email: "abc@emalupe.com", ... }

2. [Set MAILCX_API_TOKEN=tm_live_... in your MCP config]

3. list_providers
   → Now includes "mail.cx" in the provider list!

Both providers are automatically available in the current session after registration — no restart needed.

Typical Registration Verification Flow

1. create_mailbox (provider: "mail.tm")
   → { address: "abc123@somedomain.com", ... }

2. [Register on target website using the temp email address]

3. get_verification_code (address: "abc123@somedomain.com", subjectContains: "verification")
   → { code: "829451", from: "noreply@example.com", subject: "Your verification code", ... }

4. [Enter the code on the target website to complete registration]

5. delete_mailbox (address: "abc123@somedomain.com")

Manual Email Checking

1. create_mailbox (provider: "guerrillamail", username: "mytest")
   → { address: "mytest@guerrillamailblock.com", ... }

2. get_messages (address: "mytest@guerrillamailblock.com")
   → { count: 2, messages: [{ id: "1", from: "...", subject: "..." }, ...] }

3. get_message (address: "mytest@guerrillamailblock.com", messageId: "1")
   → { id: "1", from: "...", subject: "...", bodyText: "...", bodyHtml: "..." }

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

# Watch mode
npm run dev

# Test auto-registration
node test-auto-register-api.mjs maildrop   # Test MailDrop only
node test-auto-register-api.mjs mailcx     # Test mail.cx only
node test-auto-register-api.mjs all        # Test both

Architecture

┌──────────────────────────────────────────────────────┐
│                  MCP Client (Claude)                   │
│                      │                                │
│             stdio / Streamable HTTP                    │
│                      ▼                                │
│          ┌──────────────────────┐                      │
│          │  TempMail MCP Server  │                      │
│          │                      │                      │
│          │  ┌─── Tools ───────┐ │                      │
│          │  │ create_mailbox   │ │                      │
│          │  │ get_messages     │ │                      │
│          │  │ wait_for_email   │ │                      │
│          │  │ get_verification │ │                      │
│          │  │ auto_register    │ │                      │
│          │  │ ...              │ │                      │
│          │  └──────────────────┘ │                      │
│          └──────────┬───────────┘                      │
│                     │                                  │
│          ┌──────────▼───────────┐                      │
│          │  Provider Manager     │                      │
│          │  (adapter pattern)    │                      │
│          └──────────┬───────────┘                      │
│                     │                                  │
│   ┌────────┬────────┼────────┬──────────┐              │
│   ▼        ▼        ▼        ▼          ▼              │
│ Mail.tm  Guerrilla 1secmail  Catchmail  MailDrop        │
│          Mail                            Mail.cx        │
└──────────────────────────────────────────────────────┘

Auto-Register Flow (pure HTTP, no browser):
  ┌───────────────┐                    ┌───────────────┐
  │  MailDrop     │                    │  mail.cx       │
  │               │                    │                │
  │  RSA keygen   │                    │  mail.tm temp  │
  │  ↓            │                    │  mailbox       │
  │  POST register│                    │  ↓             │
  │  ↓            │                    │  POST magic    │
  │  RSA sign     │                    │  link request  │
  │  ↓            │                    │  ↓             │
  │  POST login   │                    │  Poll for email│
  │  ↓            │                    │  ↓             │
  │  POST create  │                    │  POST verify   │
  │  API key      │                    │  → API token  │
  │  → md_...     │                    │  → tm_live_... │
  └───────────────┘                    └───────────────┘

License

MIT