switch-carrier-mcp

Universal US carrier switching CLI + Model Context Protocol (MCP) server.

Switch any US carrier to any other — AT&T, Verizon, T-Mobile, Boost, Cricket, Metro, Google Fi, Mint Mobile, Visible, Consumer Cellular, US Cellular, Straight Talk, and more.

Features

• Guided wizard (switch-carrier start) — 7 prompts, then fully automated: auto-opens the carrier's PIN page, validates your info, fills the port-in form, and polls for completion.
• Session persistence — interrupted? switch-carrier resume picks up where you left off (saved to ~/.switch-session.json).
• Playwright auto-fill — headless Chromium fills the target carrier's web form and auto-submits after a 10-second review countdown.
• Status polling — checks the carrier's port status page every 60 seconds until the transfer completes, with desktop notifications and webhook support.
• Letter of Authorization (LOA) — generate a signed LOA when the target carrier requires it.
• MCP server mode — expose all 17 tools to any MCP client (Claude Desktop, Cursor, etc.) for AI-assisted switching.
• Family plan support — batch port multiple lines on the same account in one command.
• Savings estimator — calculate monthly and annual savings before committing to a switch.

Supported Carriers

| Carrier | Country | Auto-fill | eSIM | PIN validity | |---|---|---|---|---| | AT&T | 🇺🇸 | ✅ | ✅ | 4 days | | Verizon | 🇺🇸 | ✅ | ✅ | 7 days | | T-Mobile | 🇺🇸 | ✅ | ✅ | 7 days | | Boost Mobile | 🇺🇸 | ✅ | ✅ | 24 hours ⚠️ | | Cricket Wireless | 🇺🇸 | ✅ | — | 5 days | | Metro by T-Mobile | 🇺🇸 | ✅ | — | 7 days | | Google Fi | 🇺🇸 | — manual | ✅ | 30 days | | Mint Mobile | 🇺🇸 | — manual | ✅ | 30 days | | Visible | 🇺🇸 | — manual | ✅ | 30 days | | Consumer Cellular | 🇺🇸 | — manual | — | 24 hours ⚠️ | | US Cellular | 🇺🇸 | — manual | — | 30 days | | Straight Talk / TracFone | 🇺🇸 | — manual | — | 30 days | | Rogers | 🇨🇦 | — manual | — | 30 days | | Bell | 🇨🇦 | — manual | — | 30 days | | TELUS | 🇨🇦 | — manual | — | 30 days | | EE | 🇬🇧 | — manual | — | 30 days (PAC) | | Vodafone | 🇬🇧 | — manual | — | 30 days (PAC) | | O2 | 🇬🇧 | — manual | — | 30 days (PAC) |

Installation

npm install -g switch-carrier-mcp
npx playwright install chromium   # one-time: install headless browser

Or run without installing:

npx switch-carrier-mcp start

CLI Usage

Complete guided flow

switch-carrier start

Steps performed automatically:

1. Choose your current (FROM) carrier and new (TO) carrier
2. Enter your phone number
3. PIN page opens in your browser automatically
4. Enter account number, PIN, billing name, and ZIP
5. Inline validation — errors shown immediately
6. Playwright opens the target carrier's form, fills it, and submits after a 10-second countdown
7. Port status is polled every 60 seconds until complete

Options:

--dry-run     Fill form but do not submit
--no-poll     Skip status polling after submission

Resume a saved session

switch-carrier resume

Other commands

# Validate port-in info without submitting
switch-carrier validate --from att --to tmobile --phone 4155551234 --account 123456789012 --pin 1234 --billing-zip 94105

# Get a step-by-step checklist for a carrier pair
switch-carrier checklist --from verizon --to tmobile

# Get PIN generation instructions for a carrier
switch-carrier pin-instructions --carrier att

# Generate a Letter of Authorization
switch-carrier loa --from att --to verizon --phone 4155551234 --account 123456789012 --billing-name "Jane Doe" --billing-zip 94105

# Submit directly (skips the guided prompts)
switch-carrier submit --from att --to tmobile --phone 4155551234 --account 123456789012 --pin 1234 --billing-name "Jane Doe" --billing-zip 94105

# Compare carriers side-by-side
switch-carrier compare --carriers att,tmobile,mint

# Estimate monthly savings
switch-carrier savings --from att --to mint --lines 2

# Launch MCP server (for Claude Desktop / Cursor)
switch-carrier serve

MCP Server Mode

Install via Smithery

The easiest way to add switch-carrier to Claude Desktop is via Smithery:

npx @smithery/cli install switch-carrier-mcp --client claude

Manual configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "switch-carrier": {
      "command": "switch-carrier",
      "args": ["serve"]
    }
  }
}

Or with npx (no global install required):

{
  "mcpServers": {
    "switch-carrier": {
      "command": "npx",
      "args": ["-y", "switch-carrier-mcp", "serve"]
    }
  }
}

Available MCP tools (17)

| Tool | Description | |---|---| | list_carriers | List all supported carriers with eSIM, account type, and automation support | | get_switch_checklist | Step-by-step checklist for a carrier pair | | get_pin_instructions | PIN generation instructions for a carrier | | validate_port_info | Validate all fields before submission | | generate_loa | Generate a Letter of Authorization | | submit_port_request | Auto-fill and submit the port-in form | | submit_multi_line_port_request | Batch submit for family plans (multiple lines) | | check_port_status | Poll carrier status page for port progress | | get_pin_expiry_status | Check if your transfer PIN is still valid | | cancel_port_request | Get cancellation URL and steps | | get_port_history | View past port attempt log | | compare_carriers | Side-by-side carrier feature comparison | | check_coverage | Get coverage check links for a carrier + ZIP | | estimate_savings | Calculate monthly and annual cost savings | | save_port_template | Save reusable port details (PIN never stored) | | load_port_template | Load a saved port template | | list_port_templates | List all saved templates |

Registry listings

• Smithery
• mcp.so
• Glama

How Number Porting Works

1. Get your transfer PIN from your current carrier (each carrier has a different process — the pin-instructions command guides you).
2. Keep your current SIM active until you see the new carrier's signal — do not cancel your old plan first.
3. Submit the port request to your new carrier with your account number, transfer PIN, billing name, and ZIP code.
4. Wait — most ports complete in 10 minutes to 3 hours. Complex cases (landline, business) can take up to 1 business day.
5. Verify the new carrier signal, then your old plan cancels automatically.

Environment Variables

| Variable | Default | Description | |---|---|---| | HEADLESS | false | Set to true to run Playwright invisibly (no browser window) |

Development

git clone https://github.com/bty888/Switch-mcp.git
cd Switch-mcp
npm install
npx playwright install chromium

npm run dev        # watch mode MCP server
npm run cli        # run CLI via tsx (no build needed)
npm run build      # compile to dist/
npm run typecheck  # TypeScript type check only
npm test           # run all tests

License

MIT