email-provisioner-mcp

MCP server for creating Mail.com/GMX/Outlook email accounts via browser automation with IMAP custody. Also supports instant catch-all email provisioning (no browser needed).

Features

• Browser-based signup for GMX, Mail.com, and Outlook with CAPTCHA solving and phone verification
• Catch-all mode for instant email creation with no browser or proxy required
• IMAP inbox access with automatic browser-based fallback when IMAP is unhealthy
• Verification code extraction via polling with regex pattern matching
• Encrypted vault for credential storage
• Residential proxy rotation with automatic geo-fallback (CA -> US -> GB -> NL -> SE)
• Anti-detect fingerprinting via rebrowser-playwright

Install

npm install email-provisioner-mcp

Requires Node.js >= 18. Playwright browsers must be installed separately:

npx playwright install chromium

Usage

As an MCP server (stdio)

npx email-provisioner-mcp

In MCP client config

{
  "mcpServers": {
    "email-provisioner": {
      "command": "npx",
      "args": ["email-provisioner-mcp"],
      "env": {
        "TWOCAPTCHA_API_KEY": "...",
        "TEXTVERIFIED_SIMPLE_TOKEN": "...",
        "PROXY_USERNAME": "...",
        "PROXY_PASSWORD": "...",
        "CATCHALL_DOMAIN": "example.com",
        "CATCHALL_IMAP_HOST": "imap.example.com",
        "CATCHALL_IMAP_USER": "[email protected]",
        "CATCHALL_IMAP_PASSWORD": "..."
      }
    }
  }
}

Tools

| Tool | Description | |------|-------------| | email_create_account | Create an email account. Providers: catch-all (instant), gmx.com, mail.com, outlook.com. Returns email, password, and IMAP config. | | email_read_inbox | Read messages from an account's IMAP inbox. Falls back to browser-based reading if IMAP is unhealthy. | | email_wait_for_code | Poll inbox for a verification code matching sender/subject regex patterns. Configurable timeout and code pattern. | | email_list_accounts | List all accounts in the vault with provider, creation date, and IMAP health status. | | email_delete_account | Remove an account from the vault (does not delete the actual email account). | | email_check_health | Verify IMAP login works and update health status in the vault. |

Tool Reference

email_create_account

Create a new email account via browser automation with anti-detect stealth.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | provider | string | No | Email provider: gmx.com, mail.com, or outlook.com. Default: mail.com. | | first_name | string | No | First name (auto-generated if omitted). | | last_name | string | No | Last name (auto-generated if omitted). | | preferred_username | string | No | Desired username part of the email address (auto-generated if omitted). | | preferred_domain | string | No | Domain to use (e.g. mail.com, email.com). Defaults to provider primary domain. | | password | string | No | Account password (auto-generated if omitted, 16-20 chars). | | proxy_country | string | No | Proxy country code. Default: ca. Auto-retries with fallback countries (ca -> us -> gb -> nl -> se) on geo-block or abuse detection. Use "none" for direct connection (no proxy). |

email_read_inbox

Read messages from an email account by logging into webmail via browser. Checks both Inbox and Spam folders.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | No* | Account ID in the vault. | | email | string | No* | Email address (alternative to account_id). | | limit | number | No | Max messages to return. Default: 20. |

* Either account_id or email must be provided.

email_wait_for_code

Poll an email account's inbox via browser for a verification code. Logs into webmail, checks Inbox and Spam, and matches sender/subject patterns.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | No* | Account ID in the vault. | | email | string | No* | Email address (alternative to account_id). | | from_pattern | string | No | Regex pattern to match sender (e.g. "twitter\|x\\.com"). | | subject_pattern | string | No | Regex pattern to match subject (e.g. "verification\|confirm"). | | code_pattern | string | No | Regex pattern to extract the code. Default: "\\b(\\d{4,8})\\b". | | timeout_ms | number | No | Timeout in milliseconds. Default: 120000. |

* Either account_id or email must be provided.

email_list_accounts

List all email accounts in the vault.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | provider | string | No | Filter by provider: gmx.com, mail.com, or outlook.com. |

email_delete_account

Remove an email account from the vault. Does not delete the actual email account from the provider.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | Yes | Account ID to delete. |

email_check_health

Verify that browser webmail login still works for an email account. Attempts to login and find the mail client.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | No* | Account ID in the vault. | | email | string | No* | Email address (alternative to account_id). |

* Either account_id or email must be provided.

Configuration

All configuration is via environment variables.

CAPTCHA Solving (required for browser-based signup)

| Variable | Description | Default | |----------|-------------|---------| | CAPTCHA_PROVIDER | 2captcha or yescaptcha | 2captcha | | TWOCAPTCHA_API_KEY | 2Captcha API key | - | | YESCAPTCHA_API_KEY | YesCaptcha API key (if using yescaptcha provider) | - |

Phone Verification (required for browser-based signup)

| Variable | Description | Default | |----------|-------------|---------| | TEXTVERIFIED_SIMPLE_TOKEN | TextVerified API token | - |

Fallback: TEXTVERIFIED_API_KEY is also accepted if TEXTVERIFIED_SIMPLE_TOKEN is not set.

Catch-All Email (for instant provisioning)

| Variable | Description | |----------|-------------| | CATCHALL_DOMAIN | Domain with catch-all configured (e.g. example.com) | | CATCHALL_IMAP_HOST | IMAP host for the catch-all mailbox | | CATCHALL_IMAP_PORT | IMAP port (default: 993) | | CATCHALL_IMAP_USER | IMAP username for the catch-all mailbox | | CATCHALL_IMAP_PASSWORD | IMAP password |

Fallbacks: The unprefixed names EMAIL_DOMAIN, IMAP_HOST, IMAP_USER, IMAP_PASSWORD, and IMAP_PORT are also accepted when the CATCHALL_* prefixed versions are not set.

Proxy (required for browser-based signup)

| Variable | Description | Default | |----------|-------------|---------| | PROXY_USERNAME | Residential proxy username | - | | PROXY_PASSWORD | Residential proxy password | - | | PROXY_PROVIDER | iproyal, brightdata, or soax | iproyal |

Vault

| Variable | Description | Default | |----------|-------------|---------| | EMAIL_VAULT_PASSPHRASE | Encryption passphrase for the account vault | - | | EMAIL_VAULT_PATH | Path to vault file | ~/.claude-workflow/email-accounts.json |

Browser

| Variable | Description | Default | |----------|-------------|---------| | CDP_ENDPOINT | Chrome DevTools Protocol endpoint | http://127.0.0.1:9222 |

License

MIT