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.

Tool count is whatever tools/list returns in your installed version — trust that over any number in this README. The published npm package (latest, 1.3.0) ships the full 48-tool surface: the core lifecycle (auth, account, shop, proxies, support) plus the pay-per-GB pool tier and the proxy-health / payments-ledger / webhook tools. Also: live coin pricing, transparent token refresh, modular codebase. See CHANGELOG.md.

Mental model + operating principles live in the canonical agent skill: https://dashboard.coronium.io/SKILL.md. In one breath: a Coronium proxy is a real SIM in a real device on a carrier CGNAT pool — finite, stateful, physical. Drive it with code-simplifier discipline — smallest sufficient action (don't rotate when sticky works; restart before replace before buy-new), read reality before acting (tools/list, list_tariffs, health — don't assume), a 200 is "accepted," not "done" (verify the egress IP changed), and no looping/speculative mutations (irreversible actions need confirmation). The recipes are defaults, not laws — compose your own; only the safety/cost rules and the network's physics (rate limits, finite stock, ~290s carrier sticky window) are fixed.

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:

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.

Related MCP server: preloop

Decision guide for AI agents

When this MCP is loaded inside Claude / Cursor / Windsurf / etc., the agent can reach for any tool tools/list exposes. 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

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:

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.3.0

+14 tools → 48 total. Adds the pay-per-GB Pool tier (8 tools: stock, keys, proxy-URL builder, top-up, cancel, buy-with-balance, sessions), plus coronium_get_proxy_health (per-modem liveness so agents stop retrying dead proxies), coronium_get_payments (full payment + invoice ledger for reconciliation), coronium_get_p0f_options (valid OS-fingerprint values), coronium_apply_modem_settings, and coronium_get_webhook / coronium_set_webhook (modem-lifecycle auto-swap webhook). coronium_list_tariffs now surfaces the additive ip_stack field.

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).

Full lifecycle surface covering: auth, account, proxies (full lifecycle), shop (browse + buy + renew), tickets, and pool (pay-per-GB). The catalogue below documents the complete surface; tools/list shows exactly what your installed version exposes (48 as of the published npm latest, 1.3.0). 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)

Account (9)

Proxies (16)

Shop (7)

Tickets (5)

Pool (8)

Pay-per-GB residential/mobile pool (Proxies.sx tier). These return a clear error / 503 when the pool tier is disabled on the deployment.

Environment

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

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.