# dropmail-mcp

MCP server for [DropMail](https://dropmail.me/) — gives AI assistants tools to
create temporary email addresses and receive mail automatically.

## Installation

Install with pip or pipx (recommended for use in MCP client configs):

```bash
pip install dropmail-mcp
# or
pipx install dropmail-mcp
```

You can also run without installing using `uvx` — handy for a quick test in the terminal:

```bash
uvx dropmail-mcp --token YOUR_TOKEN
```

<small>Note: `uvx` may not work reliably when launched as a subprocess by MCP clients (Claude Desktop, VS Code, Copilot CLI). If your client shows "Connection closed", use `pip`/`pipx` instead.</small>

## Configuration

| Variable              | Flag            | Default                               | Description                        |
|-----------------------|-----------------|---------------------------------------|------------------------------------|
| `DROPMAIL_TOKEN`      | `--token`       | —                                     | Required. Obtain at dropmail.me/api |
| `DROPMAIL_BASE_URL`   | `--base-url`    | `https://dropmail.me/api/graphql`     | GraphQL endpoint                   |
| `DROPMAIL_LOG_LEVEL`  | `--log-level`   | `NONE`                                | Log level: `DEBUG` `INFO` `WARNING` `ERROR` `NONE` |
| `DROPMAIL_LOG_FILE`   | `--log-file`    | stderr                                | Path to log file (default: stderr) |

To use the public service, no `DROPMAIL_BASE_URL` override is needed — it defaults to `https://dropmail.me/api/graphql`.

`DEBUG` log level records the full GraphQL request (minified query + variables) and response body after each call — useful for troubleshooting.

## Claude Desktop setup

```json
{
  "mcpServers": {
    "dropmail": {
      "command": "dropmail-mcp",
      "env": {
        "DROPMAIL_TOKEN": "your-token-here"
      }
    }
  }
}
```

## VS Code / GitHub Copilot IDE setup

Add to `.vscode/mcp.json` in your workspace (VS Code 1.99+, agent mode):

```json
{
  "servers": {
    "dropmail": {
      "type": "stdio",
      "command": "dropmail-mcp",
      "env": {
        "DROPMAIL_TOKEN": "${input:dropmail-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "dropmail-token",
      "type": "promptString",
      "description": "DropMail API token (obtain at dropmail.me/api/)",
      "password": true
    }
  ]
}
```

VS Code will prompt for the token securely — it is never stored in plain text.

## GitHub Copilot CLI setup

Edit `~/.copilot/mcp-config.json` (create if it doesn't exist):

```json
{
  "mcpServers": {
    "dropmail": {
      "command": "dropmail-mcp",
      "env": {
        "DROPMAIL_TOKEN": "${DROPMAIL_TOKEN}"
      }
    }
  }
}
```

Set `DROPMAIL_TOKEN` in your shell profile (`~/.bashrc`, `~/.zshrc`, etc.),
or run `/mcp add` inside the Copilot CLI session to configure it interactively.

## Tools

| Tool               | What it does                                              |
|--------------------|-----------------------------------------------------------|
| `list_domains`     | List available `@domain` options                          |
| `create_session`   | Create a session and get a temporary address              |
| `get_session`      | Check session state, addresses, and mail count            |
| `get_inbox`        | List received emails with subject and text preview        |
| `wait_for_email`   | Block until a new email arrives (up to 180 s)             |
| `read_email`       | Read full email: text body, attachments, download URLs    |
| `add_address`      | Add a second address to an existing session               |
| `restore_address`  | Restore an old address using its restore key              |
| `delete_address`   | Remove an address from a session                          |

## Example prompts

- *"Give me a temp email and wait for the confirmation from example.com"*
- *"Sign me up for the newsletter at example.com using a throwaway address"*
- *"I need to sign up for a product trial on example.com — give me a .com temp email, wait for their email, and pull out the activation code"*
- *"Check if the password reset email has arrived and give me the link"*

## Running tests

```bash
cd mcp
pip install -e ".[dev]"

# Unit tests only
pytest tests/test_client.py tests/test_tools.py

# Integration tests (requires a running DropMail instance)
DROPMAIL_TOKEN=mytoken pytest tests/test_integration.py
```

## License

MIT
