Coronium MCP Server
Manage your Coronium mobile proxies from an AI assistant
coronium-proxy-mcp is a local stdio MCP server for Coronium customers. It lets Claude Code, Claude Desktop, Cursor and other MCP hosts check balances, list your proxies with HTTP and SOCKS5 URLs, test and rotate them, compare plans and stock, get renewal quotes and work with support tickets. It talks only to the Coronium customer API at https://api.coronium.io/api/v3.
claude mcp add coronium \ -e CORONIUM_API_TOKEN=YOUR_CORONIUM_API_TOKEN \ -e CORONIUM_TOOL_PROFILE=directory \ -- npx -y coronium-proxy-mcp@2.1.0
Installation
You need Node.js 20 or newer and a Coronium account. Create the API token in the dashboard at dashboard.coronium.io, under Account, API Access. Keep it in your host's protected configuration, never in a repository or a chat.
1. Claude Code
Add the server, then run /mcp to check that coronium is connected.
claude mcp add coronium \ -e CORONIUM_API_TOKEN=YOUR_CORONIUM_API_TOKEN \ -e CORONIUM_TOOL_PROFILE=directory \ -- npx -y coronium-proxy-mcp@2.1.0
2. Claude Desktop, Cursor and other MCP hosts
Add this to the host's MCP configuration (for Cursor, ~/.cursor/mcp.json) and restart the host.
{
"mcpServers": {
"coronium": {
"command": "npx",
"args": ["-y", "coronium-proxy-mcp@2.1.0"],
"env": {
"CORONIUM_API_TOKEN": "YOUR_CORONIUM_API_TOKEN",
"CORONIUM_TOOL_PROFILE": "directory"
}
}
}
}Set the host's tool timeout above 180 seconds: rotation, replacement and payment calls wait for the backend. If a call times out, check its outcome before acting again.
3. Claude Code plugin
The coronium-mobile-proxies plugin is available from the Coronium marketplace on GitHub (it is not listed in Anthropic's plugin directory yet). It runs the server in the directory profile, so it cannot buy, renew, top up, cancel or refund anything. Claude Code asks for the API token when you enable the plugin.
/plugin marketplace add coroniumio/coronium-proxy-mcp /plugin install coronium-mobile-proxies@coronium
The plugin needs Claude Code (it starts a local server). Details: plugin README.
What it can do
Every tool name begins with coronium_, for example coronium_get_proxies, coronium_rotate_modem, coronium_get_rotation_status, coronium_get_renewal_quote and coronium_create_ticket. The exact list depends on the tool profile; call tools/list or coronium_get_capabilities to see it.
Account and balances
Account credit, BTC and USDT balances, read as separate values.
Proxies and connection URLs
Your proxies with ready-to-use HTTP and SOCKS5 URLs, health, and a backend connectivity test.
Rotation and replacement
Rotate the IP and poll its status, replace a proxy (2 replacements per rolling 24 hours by default), download an OpenVPN profile.
Plans, stock and quotes
Countries, plans and stock by country and carrier, and renewal quotes for proxies you own.
Support tickets
List, read, create and reply to support tickets.
More in the full profile
Settings, webhooks, pool keys and Coronium Node tools. Money tools only with spending enabled.
Tool profiles and spending
CORONIUM_TOOL_PROFILE decides which tools exist.
directory
An explicit allowlist of 21 tools: balances, owned proxies, health, connectivity test, rotation and its status, replacement, OpenVPN profile, countries, plans and stock, renewal quotes, tickets, webhook read and capabilities.
No buy, renew, top-up or cancel tools. No login tool.
full
The default when CORONIUM_TOOL_PROFILE is unset. Registers every non-money tool, including login, settings, webhooks, pool keys and Coronium Node tools.
Money tools only when CORONIUM_ENABLE_SPENDING=1 is also set.
read-only
Registers only tools that change nothing. CORONIUM_READ_ONLY=true is an alias.
No money tools.
Spending is off by default.
Buy, renew, pool purchase, top-up and cancel tools exist only when CORONIUM_TOOL_PROFILE=full and CORONIUM_ENABLE_SPENDING=1 are both set. Without both, they are not registered and the server also refuses money calls on its own. A .env file in the working directory cannot turn spending on.
With spending enabled, every money tool still needs confirm:true, a UUID idempotency key and the approved amount. The tool re-reads the price right before sending and refuses if the total is now higher. No write is retried automatically. Everyone else pays in the dashboard.
Configuration
CORONIUM_API_TOKENDashboard API token (Account, API Access). CORONIUM_API_KEY is an alias.
CORONIUM_TOOL_PROFILEdirectory, full or read-only. Any other value stops the server at startup. Default: full.
CORONIUM_ENABLE_SPENDING1 or true enables money tools in the full profile. Default: off. Read only from the host environment or DOTENV_CONFIG_PATH.
CORONIUM_BASE_URLDefaults to https://api.coronium.io/api/v3. Leave it unset in normal use.
The full list, including optional login settings for the full profile, is in the README. Upgrading from 1.3.0? Read the migration notes.
Prefer code or a shell?
The same API is available as a typed TypeScript SDK and a command-line tool. Both use CORONIUM_API_TOKEN and keep buying and renewing off until you opt in.
npm install coronium-sdk
npm install -g coronium-cli coronium proxy list
Source and docs: github.com/bolivian-peru/coronium-ai. REST reference: api.coronium.io/api-docs.
FAQ
Which package should I install?
coronium-proxy-mcp on npm (version 2.1.0). The older coronium-mcp package is retired and deprecated on npm because it called API routes that do not exist. Do not use it.
Which MCP hosts does it work with?
It is a standard stdio MCP server, so it works with hosts that can launch a local command, such as Claude Code, Claude Desktop and Cursor. It needs Node.js 20 or newer.
Can the MCP server spend money?
Not by default. Buy, renew, pool purchase, top-up and cancel tools are registered only when CORONIUM_TOOL_PROFILE=full and CORONIUM_ENABLE_SPENDING=1 are both set in the host environment. Even then, each money call needs confirm:true, an idempotency key and the approved amount. The directory profile and the Claude Code plugin have no money tools.
Where do I get the API token?
In the dashboard at dashboard.coronium.io, under Account, API Access. Keep it in your MCP host configuration or secret store, never in a repository or a chat.
Is the Claude Code plugin in the Claude plugin directory?
Not yet. It is available from the Coronium marketplace on GitHub: run /plugin marketplace add coroniumio/coronium-proxy-mcp and then /plugin install coronium-mobile-proxies@coronium inside Claude Code.
Why does rotation sometimes take a while?
Rotation waits for the carrier to assign a new IP. Set the host tool timeout above 180 seconds. A rotate call returns done (new IP), rotating (poll get_rotation_status, do not resubmit) or unchanged (the carrier kept the IP, wait about 60 seconds).
Acceptable use
Coronium proxies are for lawful purposes such as app and website QA, ad verification, localisation testing and monitoring public information. Follow the Coronium Terms and the terms of every site you reach through a proxy. Questions and security reports: hello@coronium.io.