@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; latest currently 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.

Related MCP server: okx-trade-mcp

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=true the 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 read scope and restrict it to your IP address with allowed_ips.

• Trading is opt-in, with caps. If you enable it, also set CEXY_MCP_MAX_ORDER_NOTIONAL and CEXY_MCP_ALLOWED_MARKETS. With a notional cap set, place_order refuses 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 use quote_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.