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": "your-email@example.com",
        "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: hello@coronium.io
• Dashboard: dashboard.coronium.io
• Buy proxies: coronium.io/buy-mobile-proxies

License

MIT — see LICENSE.