dropmail-mcp 0.1.1

MCP server for the DropMail temporary email service

dropmail-mcp

MCP server for DropMail — 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):

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:

uvx dropmail-mcp --token YOUR_TOKEN

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.

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

{
  "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):

{
  "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):

{
  "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

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