@cexyio/mcp
The official Model Context Protocol server for the CEXY.io exchange. It lets an AI assistant (Claude Code, Claude Desktop, or any MCP client) read market data and, with your API key, your balances, orders and history.
- Read-only by default. Trading tools do not exist unless you turn them on.
- It never moves funds. There are no withdrawal, transfer or deposit-address tools, and CEXY API keys cannot withdraw anyway.
- Runs locally over stdio. It opens no network port.
- Built on the official TypeScript SDK,
@cexyio/cexy.
Status: 0.x prerelease. Tool names and outputs may still change. Pre-release:
npx -y @cexyio/mcp@next;latestcurrently points at a pre-release until 1.0.
Install
It needs Node.js 22 or newer. Nothing to install globally: MCP clients start it with npx.
Claude Code
Public market data only (no key):
claude mcp add cexy -- npx -y @cexyio/mcp
With your account (read-only key):
claude mcp add cexy \
-e CEXY_API_KEY=ak_your_key_here \
-e CEXY_API_SECRET=your_secret_here \
-- npx -y @cexyio/mcp
With trading enabled and guardrails (see Safety first):
claude mcp add cexy \
-e CEXY_API_KEY=ak_your_key_here \
-e CEXY_API_SECRET=your_secret_here \
-e CEXY_MCP_ENABLE_TRADING=true \
-e CEXY_MCP_MAX_ORDER_NOTIONAL=100 \
-e CEXY_MCP_ALLOWED_MARKETS=BTC/USDT,ETH/USDT \
-- npx -y @cexyio/mcp
Claude Desktop
Add this to claude_desktop_config.json (Settings, Developer, Edit Config) and restart Claude Desktop:
{
"mcpServers": {
"cexy": {
"command": "npx",
"args": ["-y", "@cexyio/mcp"],
"env": {
"CEXY_API_KEY": "ak_your_key_here",
"CEXY_API_SECRET": "your_secret_here"
}
}
}
}
Leave out the env block for public data only. Add "CEXY_MCP_ENABLE_TRADING": "true" (and the
guardrails) only if you want the assistant to place orders.
Other MCP clients
Run npx -y @cexyio/mcp as a stdio server and pass the configuration as environment variables.
Configuration
The server refuses to start when only one of the key and the secret is set, when the base URL
is not https:// (outside the loopback exception above), or when CEXY_MCP_ENABLE_TRADING has an
unrecognised value such as tru. It never echoes
either of them in tool output, errors or logs.
Tools
Every read tool is annotated readOnlyHint: true and openWorldHint: true. The trading tools
are annotated destructiveHint: true.
Public (always available, no key):
Read key (registered only when CEXY_API_KEY and CEXY_API_SECRET are set; the key needs the read scope):
Trade (registered only when CEXY_MCP_ENABLE_TRADING=true and a key is set; the key needs the trade scope):
Never available: withdrawals, transfers (including sub-account transfers), any other sub-account action (reading a sub-account's balances is the only one), liquidity-pool join/exit, deposit-address lookup (the API creates an address on first use), API-key management, login/2FA, exports and any admin function. A test asserts that none of these ever appear.
Output
Results are compact JSON (structuredContent), plus a text block with a one-line summary followed
by the same JSON, for clients that read only text. Amounts are decimal strings (never floats) and
timestamps are ISO 8601. Lists default to 10-50 items; paged tools return next_cursor (or
next_offset) to fetch more. No result is larger than about 20 KB: longer lists are trimmed and
marked truncated: true with a note.
Errors come back as MCP tool errors with a structured body:
{ "error": { "code": "FORBIDDEN", "message": "...", "retryable": false, "request_id": "..." } }
code is the API error code (e.g. INSUFFICIENT_FUNDS, RATE_LIMITED), or one of this server's:
GUARDRAIL_REJECTED, INVALID_INPUT, TIMEOUT, CONNECTION_ERROR, ORDER_STATE_UNKNOWN,
INTERNAL_ERROR. Quote the request_id when you contact support.
Safety
- Read-only by default. Without
CEXY_MCP_ENABLE_TRADING=truethe trading tools are not registered at all, so the assistant cannot see or call them. - Use a read-only key unless you want trading. Create the key with only the
readscope and restrict it to your IP address withallowed_ips. - Trading is opt-in, with caps. If you enable it, also set
CEXY_MCP_MAX_ORDER_NOTIONALandCEXY_MCP_ALLOWED_MARKETS. With a notional cap set,place_orderrefuses any order whose value it cannot bound: limit buys use price x quantity, limit sells use the higher of the price and the best bid, market buys are priced by walking the current asks (or usequote_quantity, a budget that includes the taker fee), market sells use the best bid, and stop orders whose fill price depends on a future book are refused. The check is made against the book at the time of the call; fast markets can move. - Orders are real and irreversible once filled. Ask your assistant to confirm each order with you; most MCP clients also ask for approval before calling a tool marked destructive.
- No withdrawal tools exist, and CEXY API keys cannot withdraw or transfer funds anyway.
- The server runs locally over stdio, opens no port and sends no telemetry.
Rate limits
The exchange allows about 120 requests per minute per IP without a key, and about 600 per minute
per API key. The SDK underneath throttles itself below that (100/min without a key, 300/min with
one) and adapts to the server's X-RateLimit-* headers. Most tools make one request;
get_server_status and list_assets make two, and place_order with a notional cap may read the
order book first. A RATE_LIMITED error includes retry_after_ms.
Development
npm install
npm run lint && npm run typecheck && npm test
npm run build # dist/cli.js (the bin) and dist/index.js
npm run test:live # opt-in: a few unauthenticated GETs to api.cexy.io
The server depends on the published SDK, pinned to an exact version (@cexyio/cexy 0.1.0-dev.19).
Security
See SECURITY.md. Never paste real API keys or secrets into issues.
License
MIT, see LICENSE.