Coronium Mobile Proxy MCP Server

MCP (Model Context Protocol) server for Coronium.io mobile (4G/5G) proxy management. Drive the full proxy lifecycle — list, rotate, replace, test, configure auto-rotation, buy, renew, manage subscriptions, open tickets — directly from Claude, Cursor, Cline, VS Code, Zed, Continue, and any other MCP-compatible host. Manage your account at dashboard.coronium.io.

v1.2.0 ships 34 tools (up from 6), full programmatic surface, live coin pricing, transparent token refresh, and a modular codebase. See CHANGELOG.md for details.

Which Coronium MCP do I want?

Two MCP servers exist and both hit the same backend (https://api.coronium.io/api/v3). Pick by your starting state:

| You are… | Use | Why | |---|---|---| | A Coronium customer with an existing dashboard.coronium.io email/password | coronium-proxy-mcp (this repo) | 34 tools across the full lifecycle: tickets, low-balance alerts, OS fingerprinting, modem metadata, account settings, plus the 7 core verbs | | An AI agent or a new user who wants one-command signup, no email | coronium-cli + coronium-mcp | Voucher-gated, wallet-bound (SIWE) signup. 7 minimal verbs. npx -y coronium-cli init --voucher cor_v1_… and you have a working JWT |

The two MCPs are intentional siblings, not duplicates — different auth model, different tool depth. Once signed in, both produce JWTs against the same API, so you can switch later if needs change.

Decision guide for AI agents

When this MCP is loaded inside Claude / Cursor / Windsurf / etc., the agent can reach for any of 34 tools. The right choice usually isn't "what's the closest tool name match" — these tools have real semantic differences. Read this once before driving the surface.

Rotate vs Replace — they are NOT interchangeable

| Symptom | Use | Cost | Why | |---|---|---|---| | IP got banned by the target site, modem otherwise healthy | coronium_restart_modem | free | Same modem, fresh IP from the carrier. ~20-second operation. | | Modem hasn't responded in N minutes, multiple test_modem failures | coronium_replace_modem | free (subscription transfers) | Swap to a different physical modem in the same country. Use this when rotation alone keeps yielding the same dead IP. | | Need a different country/carrier | Buy a new one + release the old | $$ | Rotate/replace stay within country. |

Anti-pattern: don't loop coronium_restart_modem more than 2 times — if rotation keeps returning the same IP, the carrier isn't releasing it. Switch to coronium_replace_modem. The backend's stuck-rotation janitor (deployed 2026-04-30) auto-clears stale "rotating" states within 5 min, so a hung rotation isn't a permanent block.

Stock-out handling

coronium_buy_modems_with_balance returns 4xx if the requested country has no inventory. Don't loop the same call. Instead:

1. coronium_list_free_modems — confirms what stock exists right now
2. If empty for the target country, fall back to a neighbouring market (US ↔ CA, DE ↔ NL ↔ AT, UK ↔ IE) or alert the human
3. coronium_list_tariffs — surfaces price across countries so you can compare

Reading balance correctly

coronium_get_balance returns three numbers:

• account_credit — USD wallet, what's actually spent by buy/renew tools
• crypto deposits: — held but unspent crypto (BTC/USDT/etc.). Will convert to account_credit when deposit is detected; not directly spendable.
• total value — informational, sum across both

Always compare a planned purchase against account_credit, not total value. A user with $0 account_credit and $50 in undeposited crypto cannot buy until the deposit is processed.

Rotation interval — pick by use case

coronium_set_rotation_interval takes seconds. Common values:

| Use case | Interval | Notes | |---|---|---| | High-volume scraping | 60 s | Maxes carrier rotation cadence; some carriers throttle below 90s | | Account farming | 300 s (5 min) | Reduces detection from rotation-frequency fingerprints | | Long-lived persona | 1800 s (30 min) | Or 0 (disable auto-rotate, rotate manually only) | | Sticky session | 0 | Manual control via coronium_restart_modem |

When to open a ticket vs retry

Open a ticket via coronium_create_ticket when:

• A modem has been "replaced" twice in 24h and still doesn't work — likely server-level issue
• A payment shows status: pending for >10 min after coronium_buy_modems_with_balance returned a payment_id
• An ext_ip never updates despite repeated successful rotations (rare; janitor should catch this)

Don't open a ticket for:

• Stock-out (try a different country first)
• "My IP got banned" (rotate / replace handles this)
• "Speed is slow" (carrier-side; not actionable by support)

Auto-login posture

If CORONIUM_LOGIN and CORONIUM_PASSWORD are set in the MCP env, don't call coronium_login proactively. The MCP auto-logs-in on the first 401 and caches the token at ~/.coronium/token.enc (AES-256-CBC). Manual coronium_login is only needed for explicit account switching or token diagnostics.

Country/carrier selection heuristics

• Target site is geo-fenced: pick the same country as the target audience. e.g. US TikTok → US carrier.
• Captcha / fraud-detection sensitivity: prefer 5G T-Mobile (US) or Three (UK) — carrier-grade NAT pools rotate aggressively, so individual IPs look "real residential mobile" rather than datacenter.
• Cost-sensitive: list tariffs by coronium_list_tariffs --country PL (Poland Play / Plus) — cheap, high-volume EU pool.
• Asia-Pacific: stock thin. Always coronium_list_free_modems --country TH/AU/NZ first.

Tool-naming distinction (across MCPs)

If the agent has both this MCP and the wallet-bound coronium-mcp loaded, the tool prefixes tell it which auth path is active:

• coronium_* (this server) → email/password auth, full lifecycle, existing-customer mode
• <verb>_<noun> like proxy_rotate, proxy_buy (coronium-mcp) → wallet/SIWE auth, agent-native mode

Don't mix-and-match in the same session unless you've confirmed the JWTs are the same identity.

Prerequisites

• A Coronium.io account — sign up via the dashboard
• Node.js 18+ installed

Quick Start

1. Install

git clone https://github.com/coroniumio/coronium-proxy-mcp.git
cd coronium-proxy-mcp
npm install
npm run build

2. Configure your AI tool

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "coronium": {
      "command": "node",
      "args": ["/absolute/path/to/coronium-proxy-mcp/dist/server.js"],
      "env": {
        "CORONIUM_LOGIN": "[email protected]",
        "CORONIUM_PASSWORD": "your-password"
      }
    }
  }
}

Cursor IDE / Cline / VS Code Copilot / Zed / Continue

Same shape — add to the host's MCP config (.cursor/mcp.json, Cline's MCP settings, etc).

3. Restart your tool

Talk to your AI: "list my Coronium proxies", "rotate the Polish one", "show my balance", "open a ticket about modem cor_US_xxx not working".

What's new in 1.2.0

Auto-login: set CORONIUM_LOGIN/CORONIUM_PASSWORD once and forget about token management — any tool that hits a 401 transparently re-mints and retries. No more "your token expired, please run coronium_get_token".

Live coin pricing: balance views now show USD valuation pulled live from CoinGecko (60s in-memory cache, falls back gracefully on rate limit).

34 tools covering: auth, account, proxies (full lifecycle), shop (browse + buy + renew), and tickets. See Tool catalogue below.

Modular codebase: src/{config,logger,token-store,api-client,prices,formatters}.ts plus src/tools/{auth,account,proxies,shop,tickets}.ts. The 2010-line single-file from 1.1.x is gone.

Tool catalogue

Auth (3)

| Tool | Description | |------|-------------| | coronium_login | Authenticate with email + password. Most other tools auto-login on 401, so explicit calls are only needed for re-auth or account switching. | | coronium_check_token | Verify the cached token is still valid. | | coronium_logout | Clear the encrypted token cache. |

Account (6)

| Tool | Description | |------|-------------| | coronium_get_account | Profile, role, contact, business data, 2FA state. | | coronium_get_balance | Unified multi-currency balance: account credit + crypto, all in USD with live prices. | | coronium_get_crypto_balance | Legacy crypto-only view (BTC/USDT/etc with deposit addresses). | | coronium_get_credit_cards | Saved Stripe cards (last-4 digits + brand). | | coronium_get_low_balance_threshold | Get configured email-alert tiers (USD). | | coronium_set_low_balance_threshold | Set email-alert tiers — e.g. [100, 300]. |

Proxies (13)

| Tool | Description | |------|-------------| | coronium_get_proxies | List proxies with optional filters (country_code, online_only, expiring_within_days). | | coronium_get_proxy | Full detail for one proxy by _id or name. | | coronium_restart_modem | Authenticated rotation via /v3/modems/:id/restart. | | coronium_get_rotation_status | Poll real-time rotation status (idle / rotating / success / failed). | | coronium_rotate_modem | Token-based rotation via the public reset service (no API token needed). | | coronium_test_modem | Live connectivity probe through the proxy. | | coronium_replace_modem | Swap a broken modem for a working one (subscription transfers). | | coronium_set_rotation_interval | Configure auto-rotation cadence in seconds (0 = manual only). | | coronium_change_proxy_password | Rotate the HTTP/SOCKS proxy password. | | coronium_set_modem_metadata | Free-form label, ≤200 chars. | | coronium_set_modem_os | p0f Android/iOS/Windows/etc fingerprint preset. | | coronium_cancel_modem | Cancel auto-renew (modem stays usable until current expiry). | | coronium_get_openvpn_config | Download .ovpn config (when supported by the modem). |

Shop (7)

| Tool | Description | |------|-------------| | coronium_list_countries | Countries with stock + free-modem counts. | | coronium_list_tariffs | Available price plans (with optional country filter). | | coronium_list_free_modems | Live free-modem inventory. | | coronium_check_coupon | Validate a coupon code. | | coronium_buy_modems_with_balance | Buy 1+ modems using account credit. | | coronium_renew_modems_with_balance | Renew existing modems. | | coronium_get_payment_status | Check status of a payment by id. |

Tickets (5)

| Tool | Description | |------|-------------| | coronium_list_tickets | List your tickets (filter by open / closed / all). | | coronium_get_ticket | Full ticket detail with replies. | | coronium_create_ticket | Open a new ticket. | | coronium_reply_to_ticket | Add a reply. | | coronium_archive_ticket | Close from the customer side. |

Environment

cp .env.example .env
# edit .env with your credentials

| Variable | Default | Purpose | |----------|---------|---------| | CORONIUM_LOGIN | — | Account email | | CORONIUM_PASSWORD | — | Account password | | CORONIUM_BASE_URL | https://api.coronium.io/api/v3 | Canonical production API base. The OpenAPI spec at https://dashboard.coronium.io/api-docs/ lists this as the single supported server URL. | | CORONIUM_ROTATION_URL | https://mreset.xyz | Token-based rotation endpoint | | CORONIUM_PRICES_URL | https://api.coingecko.com/api/v3/simple/price | Coin price source | | CORONIUM_AUTO_LOGIN | 1 | Set to 0 to disable transparent re-auth on 401 | | TOKEN_ENCRYPTION_KEY | random per process | Pin to a 64-hex value to keep cache across restarts | | LOG_LEVEL | info | error / warn / info / debug |

Security

• Tokens encrypted at rest with AES-256-CBC under a scrypt-derived key
• Credentials live in env vars or .env — never written to source files
• Cache directory: ~/.coronium/ (token + crypto deposit addresses)
• All logging goes to stderr; stdout is reserved for MCP JSON-RPC

Development

npm run dev           # tsx watch mode
npm test              # vitest
npm run build         # tsc → dist/
npm run typecheck     # tsc --noEmit

LOG_LEVEL=debug npm run dev

Sibling project — wallet-bound MCP

For agent-native onboarding (no email/password — wallet keypair + voucher), see @coronium/mcp in the coronium-ai monorepo. Tool surfaces are intentionally similar so an agent can substitute one for the other based on the user's auth model.

Support

• Issues: GitHub
• Email: [email protected]
• Dashboard: dashboard.coronium.io
• Buy proxies: coronium.io/buy-mobile-proxies

License

MIT — see LICENSE.