# tempmail-mcp

MCP server for disposable email. Gives an assistant its own throwaway inbox, then
hands back the confirmation code out of the message that arrives.

The problem it solves: an agent walking through a signup flow hits the point where
a real email address is needed, and a human has to step in to read a code out of
their inbox. At that moment the automation stops being automation.

## Install

```json
{
  "mcpServers": {
    "tempmail": {
      "command": "npx",
      "args": ["-y", "tempmail-mcp"],
      "env": {
        "TEMPMAIL_API_KEY": "tm_your_key_here"
      }
    }
  }
}
```

Get a key at [tempmailgenerator.net/account](https://tempmailgenerator.net/account/).
Free, no card, one key per account.

For Claude Code:

```sh
claude mcp add tempmail --env TEMPMAIL_API_KEY=tm_your_key -- npx -y tempmail-mcp
```

## Tools

| Tool | What it does |
|---|---|
| `create_mailbox` | Take an address. Random name and domain unless you ask otherwise. |
| `wait_for_code` | Block until mail arrives, return the code and the activation link. |
| `list_messages` | What is in the inbox, newest first, with previews. |
| `read_message` | Full body of one message. |
| `delete_mailbox` | Clean up when done. |

`wait_for_code` is the one that matters. It holds the connection until the message
lands rather than polling, so the assistant does not burn turns checking an empty
inbox, and it returns the digits already extracted instead of a wall of HTML for
the model to squint at.

## A typical run

1. `create_mailbox` gives `laura.ellis5427@...`
2. The agent submits that address to the signup form it is working through.
3. `wait_for_code` returns `481902` and the confirmation link a second later.
4. The agent finishes the flow.

## Limits and manners

Mailboxes live 24 hours. One key allows 300 new mailboxes an hour and 100 alive at
once, which is far past what an interactive agent needs and short of what a signup
farm wants.

Addresses come from a pool reserved for automation and are recognisably
disposable. Point this at systems you own or test. Pointed at somebody else's
service to mass produce accounts, it becomes their incident and then ours.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `TEMPMAIL_API_KEY` | required | Your key. |
| `TEMPMAIL_BASE_URL` | `https://tempmailgenerator.net` | Only for self-hosted installs. |

API reference: <https://tempmailgenerator.net/api/>

## License

MIT