x-browser-mcp

MCP server for X/Twitter browser automation -- account creation, profile setup, and cookie harvesting via Playwright.

Features

• Full signup automation with CAPTCHA solving (Arkose/FunCaptcha), email verification, and phone verification
• Profile setup via browser (avatar, banner, bio, display name)
• Cookie harvesting to extract auth_token + ct0 for HTTP API use
• Browser login for existing accounts
• Account health checks (suspension/lock detection)
• Catch-all email generation with persistent registry and tagging
• Anti-detect fingerprinting via rebrowser-playwright with stealth patches
• Encrypted vault for credential and cookie storage (shared with x-client-mcp)

Install

npm install x-browser-mcp

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

npx playwright install chromium

Usage

As an MCP server (stdio)

npx x-browser-mcp

In MCP client config

{
  "mcpServers": {
    "x-browser": {
      "command": "npx",
      "args": ["x-browser-mcp"],
      "env": {
        "TWOCAPTCHA_API_KEY": "...",
        "TEXTVERIFIED_SIMPLE_TOKEN": "...",
        "IMAP_HOST": "imap.example.com",
        "IMAP_USER": "[email protected]",
        "IMAP_PASSWORD": "...",
        "EMAIL_DOMAIN": "example.com",
        "PROXY_USERNAME": "...",
        "PROXY_PASSWORD": "..."
      }
    }
  }
}

Tools

| Tool | Description | |------|-------------| | x_create_account | Full signup flow with CAPTCHA + email/phone verification. Auto-generates identity if not provided. Supports pre-provisioned emails (with per-account IMAP credentials) or catch-all generation. Pass use_phone: true to stay on the phone verification path when Castle.io flags the email domain. | | x_verify_email | Read a verification code from an IMAP inbox for a given email address. | | x_verify_phone | Poll for an SMS verification code using a verification_id from a prior signup step. | | x_setup_profile | Set avatar, banner, bio, and display name via browser automation. | | x_harvest_cookies | Log in and extract auth_token + ct0 cookies for HTTP API use. | | x_browser_login | Log in to an existing account; keeps the browser session open. | | x_check_account_health | Verify account is not suspended or locked by attempting browser login. | | x_list_emails | List all generated emails from the registry. Filter by unused. | | x_generate_emails | Generate catch-all email addresses and persist them to the registry. | | x_tag_email | Tag an email in the registry with a purpose string. |

Tool Reference

Detailed parameter documentation for every tool. All parameters are optional unless marked required.

x_create_account

Create a new X/Twitter account with full signup automation including CAPTCHA solving, email verification, and phone verification.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | no | Display name for the account. Auto-generated if omitted. | | handle | string | no | Desired @handle. X may assign one regardless. | | password | string | no | Account password (min 8 chars). Auto-generated if omitted. | | birth_year | number | no | Birth year (1970-2006 for 18+). | | birth_month | number | no | Birth month (1-12). | | birth_day | number | no | Birth day (1-31). | | email | string | no | Pre-provisioned email address. If omitted, generates one using the catch-all domain. | | email_imap_host | string | no | IMAP host for the pre-provisioned email (e.g. imap.mail.com). Required when email is provided and is not on the catch-all domain. | | email_imap_port | number | no | IMAP port for the pre-provisioned email. Default: 993. | | email_imap_user | string | no | IMAP username for the pre-provisioned email (usually the email address itself). | | email_imap_password | string | no | IMAP password for the pre-provisioned email. | | use_phone | boolean | no | Stay on the phone verification path instead of switching to email. Set this to true when Castle.io flags the email domain -- the signup flow will skip the email-to-phone switch and proceed directly with SMS verification. | | cdp_endpoint | string | no | Chrome DevTools Protocol endpoint (e.g. ws://localhost:9300). Launches a new browser if omitted. |

x_verify_email

Read a verification code from an IMAP inbox for a given email address.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | email | string | yes | Email address to check for the verification code. | | timeout_ms | number | no | Timeout in milliseconds. Default: 120000. |

x_verify_phone

Poll for an SMS verification code using a verification_id returned by a prior signup step. Does not request a new phone number -- it checks the status of an existing verification.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | verification_id | string | yes | Verification ID from the signup flow. | | timeout_ms | number | no | Timeout in milliseconds. Default: 120000. |

x_setup_profile

Set up an account profile (avatar, banner, bio, display name) via browser automation. Logs in first, then applies changes.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault. | | display_name | string | no | Display name to set. | | bio | string | no | Bio text to set. | | avatar_path | string | no | Path to avatar image file. | | banner_path | string | no | Path to banner image file. | | cdp_endpoint | string | no | CDP endpoint to connect to. |

x_harvest_cookies

Log in and extract auth_token + ct0 cookies from a browser session for HTTP API use. Updates the vault with fresh cookies.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault. | | cdp_endpoint | string | no | CDP endpoint to connect to. |

x_browser_login

Log in to an existing X account in a browser session. The session stays open after login for further interaction.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault. | | cdp_endpoint | string | no | CDP endpoint to connect to. |

x_check_account_health

Check if an account is healthy (not suspended or locked) by attempting a browser login and inspecting the page.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault. | | cdp_endpoint | string | no | CDP endpoint to connect to. |

x_list_emails

List all previously generated emails from the registry. Shows email, creation date, and what account it was used for (if any).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | unused_only | boolean | no | If true, only return emails not yet assigned to an account. |

x_generate_emails

Generate one or more unique email addresses using the catch-all domain. Emails are persisted to the registry.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | count | number | no | Number of emails to generate. Default: 1, max: 100. | | purpose | string | no | Tag all generated emails with a purpose (e.g. "x-account", "newsletter-signup"). |

x_tag_email

Tag an existing email in the registry with a purpose string. Useful for tracking what each email was used for.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | email | string | yes | The email address to tag. | | purpose | string | yes | What this email is being used for. |

Configuration

All configuration is via environment variables.

CAPTCHA Solving (required)

| Variable | Description | Default | |----------|-------------|---------| | CAPTCHA_PROVIDER | 2captcha, yescaptcha, or anticaptcha | 2captcha | | TWOCAPTCHA_API_KEY | 2Captcha API key | - | | YESCAPTCHA_API_KEY | YesCaptcha API key | - | | ANTICAPTCHA_API_KEY | Anti-Captcha API key | - |

Phone Verification (required)

| Variable | Description | |----------|-------------| | TEXTVERIFIED_SIMPLE_TOKEN | TextVerified API token | | TEXTVERIFIED_EMAIL | TextVerified account email (optional, for auth) |

Email / IMAP (required for email verification)

| Variable | Description | Default | |----------|-------------|---------| | EMAIL_DOMAIN | Catch-all domain for generating email addresses | - | | IMAP_HOST | IMAP server host | - | | IMAP_PORT | IMAP server port | 993 | | IMAP_USER | IMAP username | - | | IMAP_PASSWORD | IMAP password | - |

Proxy (required)

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

Vault

| Variable | Description | Default | |----------|-------------|---------| | X_VAULT_PASSPHRASE | Encryption passphrase for the account vault | - | | X_VAULT_PATH | Path to vault file | ~/.claude-workflow/x-accounts.json |

Browser

| Variable | Description | |----------|-------------| | CDP_ENDPOINT | Chrome DevTools Protocol endpoint (optional; launches browser if omitted) |

Account State Machine

Accounts progress through these states:

created -> email_verified -> phone_verified -> profile_setup -> warming -> active
                                                                           |
                                                                    suspended / locked

The vault file is shared with x-client-mcp, which picks up accounts in phone_verified or later states for HTTP API operations.

License

MIT