tmailor-mcp

MCP server for the Tmailor Open API. It gives AI agents (Claude, Cursor, VS Code Copilot and any other MCP client) real, receive-only temporary email addresses: sign up somewhere, wait for the email, get the one-time code or the verification link.

You:   Sign up on example.com with a temporary email and confirm the account.
Agent: create_mailbox -> k3x9q2m7@picdirect.net
       (fills in the sign-up form)
       wait_for_message -> otp "482913", links ["https://example.com/confirm?t=..."]

Billing counts mailboxes, not requests: creating an address uses 1 unit of quota, while waiting for and reading mail is free. Addresses never expire.

Requirements

• A Tmailor API key: sign in at https://platform.tmailor.com and create one under API keys.
• uv (for uvx) or Python 3.10+.
• On the Free plan the API only accepts calls from your allowlisted IP: add the public IP of the computer that runs the MCP server under IP allowlist. Paid plans accept calls from any IP.

Install

The server runs locally over stdio. The API key is read from the TMAILOR_API_KEY environment variable.

Claude Code

claude mcp add tmailor -e TMAILOR_API_KEY=tmk_live_... -- uvx tmailor-mcp

Claude Desktop

Edit claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "tmailor": {
      "command": "uvx",
      "args": ["tmailor-mcp"],
      "env": { "TMAILOR_API_KEY": "tmk_live_..." }
    }
  }
}

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project) uses the same mcpServers block as above.

VS Code

.vscode/mcp.json. The key is asked once and stored by VS Code instead of being written in the file:

{
  "inputs": [
    { "type": "promptString", "id": "tmailor-key", "description": "Tmailor API key", "password": true }
  ],
  "servers": {
    "tmailor": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tmailor-mcp"],
      "env": { "TMAILOR_API_KEY": "${input:tmailor-key}" }
    }
  }
}

Without uv

pip install tmailor-mcp
TMAILOR_API_KEY=tmk_live_... tmailor-mcp

Tools

Tools take and return email addresses only. The address tokens of the API stay inside the server process, so they never end up in the conversation.

Security notes

• Email content is untrusted. Anyone can send mail to an address. The server returns plain text only (no HTML), cuts it to max_chars, and marks every message with untrusted_content_notice. Agents should use mail as data (codes, links) and never follow instructions written inside it.
• Keep the key out of shared files. Prefer the VS Code inputs prompt, or a user-level config file that is not committed to a repository. Revoke a leaked key at https://platform.tmailor.com/keys.
• Paid plans accept API calls from any IP, so a leaked key can be used from anywhere until you revoke it.
• wait_for_message never returns the same message twice within one server process. Two MCP servers waiting on the same address at the same time (for example two agents sharing one key) can both receive the same message.

Configuration

Links

• API reference: https://platform.tmailor.com/docs
• Python SDK used by this server: tmailor-sdk
• Plans: https://platform.tmailor.com/plans

License

MIT