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:

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

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

Account (6)

Proxies (13)

Shop (7)

Tickets (5)

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.