Install

Requirement: Node.js ≥ 20 (node --version to check). No clone, no build — the MCP client downloads the package on first launch via npx.

Quick install — Claude Code CLI (recommended)

One command, no JSON editing.

Public data only (no API key needed)

If you just want market data — prices, order books, candles, public ticker stream — skip the env block entirely:

claude mcp add bitkub-trading-mcp -- npx -y bitkub-trading-mcp

The 9 public REST tools and the 1 public WebSocket ticker tool work immediately. The 12 secure REST tools and 2 private WebSocket tools register but each call returns an auth error explaining how to add keys.

With API key (full features — your wallet or order and match transaction)

Replace the two placeholder values with your real Bitkub key + secret. See Add your API key for how to generate them.

claude mcp add bitkub-trading-mcp \
  -e BITKUB_API_KEY=your_real_key_here \
  -e BITKUB_API_SECRET=your_real_secret_here \
  -- npx -y bitkub-trading-mcp

Make it available across all projects

Add -s user to either command above:

claude mcp add bitkub-trading-mcp -s user -- npx -y bitkub-trading-mcp

After running any of these, /exit and claude again. Verify with /mcp.

Manual install (Claude Desktop or hand-editing config)

If you're using Claude Desktop, or prefer to edit the config file by hand, follow the three steps below.

1. Open your MCP client config file

If the file doesn't exist yet, create it with { "mcpServers": {} } as the contents.

2. Add the bitkub-trading-mcp block

Inside the mcpServers object, add this entry. If you already have other MCP servers configured, separate them with a comma — it's a normal JSON object.

{
  "mcpServers": {
    "bitkub-trading-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bitkub-trading-mcp"],
      "env": {
        "BITKUB_API_KEY": "your_api_key_here",
        "BITKUB_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

Replace the two your_..._here placeholders with your real Bitkub key + secret — see Add your API key below for how to generate them.

3. Restart the client and verify

• Claude Code: /exit then claude again. Then run /mcp.
• Claude Desktop: quit the app fully (right-click tray icon → Quit on Windows; Cmd+Q on macOS) and relaunch.

You should see bitkub-trading-mcp connected with 24 tools. The first launch downloads the package from npm (~5–10 seconds); subsequent launches use the cached version.

If BITKUB_API_KEY/BITKUB_API_SECRET are absent, the public tools still work; secure tools register but each call returns an auth error explaining how to add the env block.

Add your API key

Public REST tools and the public ticker WebSocket tool work without a key. The 12 secure REST tools and the 2 private WebSocket tools need a Bitkub API key + secret in your MCP client config's env block — never as tool arguments. The LLM never sees the secret.

1. Generate a key on Bitkub

1. Go to https://www.bitkub.com/en/api-management and log in if prompted.
2. Click Create new API key.
3. Recommended: enable read-only permissions only — uncheck Trade and Withdraw scopes. The server only exposes read-only endpoints, so giving the key write scopes is wasted attack surface.
4. Copy the API Key and API Secret before closing the dialog (the secret is shown only once).

2. Paste into the env block

Replace the two your_..._here placeholders in whichever Install option you picked above with the real key + secret. Save, restart the MCP client.

3. Verify the key actually works

If you have the source checked out:

cd /path/to/bitkub-trading-mcp
eval "$(bun -e 'const c=await Bun.file(`${process.env.HOME}/.claude.json`).json();const e=c.mcpServers[`bitkub-trading-mcp`].env;console.log(`export BITKUB_API_KEY=${e.BITKUB_API_KEY}\nexport BITKUB_API_SECRET=${e.BITKUB_API_SECRET}`)')" && bun scripts/test-auth.ts

PASS means the key + signing path is working end-to-end against Bitkub.

Otherwise, just ask Claude "What's in my Bitkub wallet?" — if it returns balances, the key works.

Public tools

Secure tools (read-only, auth required)

Bitkub v4 is used wherever it has an equivalent; v3 endpoints are kept only where v4 has not yet shipped one. v4 uses GET with query params; v3 mostly used POST with body. Auth signing is identical for v3 and v4.

Auth signing (v3 and v4): X-BTK-APIKEY, X-BTK-TIMESTAMP (Unix ms), X-BTK-SIGN = HMAC-SHA256 of {ts}{METHOD}{path}{?query | body}, hex lowercase. For POSTs the exact JSON bytes sent on the wire are signed.

References: https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api.md · https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api-v4.md

WebSocket tools (snapshot)

Each call opens a WebSocket, collects events for a bounded duration, then closes. Stateless — no long-lived subscriptions, no MCP notifications.

Args (every tool):

• duration_ms? — int, milliseconds. Defaults and caps as in the table above.
• bitkub_ws_ticker_snapshot.sym — required (e.g. btc_thb).
• bitkub_ws_order_updates.sym / bitkub_ws_match_updates.sym — optional post-filter on data.symbol.

Response shape:

{
  "events": [/* raw Bitkub payloads, in receive order */],
  "count": 0,
  "duration_ms_actual": 30000,
  "stream": "order_update",
  "started_at": "2026-05-10T17:00:00.000Z",
  "ended_at":   "2026-05-10T17:00:30.000Z"
}

If the WS closes before the window ends, the response also includes closed_early: true and closed_reason: "...".

Race-condition note: the private streams only deliver events that occur AFTER subscribe is sent. If you want to observe an order's full lifecycle, call bitkub_ws_order_updates in parallel with the order placement — or call bitkub_order_info afterward for the authoritative final state.

Concurrency cap: Bitkub permits at most 5 concurrent private WebSocket connections per API key. The server detects "too many concurrent" closes and surfaces them with a clear message.

Excluded streams (intentional): the public market.trade.* channel (Bitkub deprecates it 2026-05-18) and the public orderbook channel (uses numeric pairing_id instead of symbol; REST bitkub_depth is a better fit).

References: https://github.com/bitkub/bitkub-official-api-docs/blob/master/websocket-api.md · https://github.com/bitkub/bitkub-official-api-docs/blob/master/private-websocket.md

Usage examples

Tools are invoked by Claude based on what you ask in plain English. The "you say" rows show the kind of prompt that triggers the tool; the "tool" rows show what gets called under the hood (you can verify with /mcp → tool history). All examples assume the server is registered and connected.

Public REST — market data (no key needed)

Private REST — your account (key required, read-only)

Public WebSocket — live ticker (no key)

Caveat: Bitkub sometimes closes the public ticker stream after just a few seconds during low activity. The response will include closed_early: true when that happens — Claude can rerun if needed.

Private WebSocket — order / match streams (key required)

Race-condition recipe. Private WS only delivers events that occur AFTER subscribe — to capture an order's full lifecycle:

"Place a BTC limit buy at 2.7M for 0.0001 BTC, and IN PARALLEL watch order_updates for 60 seconds. Then call bitkub_order_info to confirm final state."

In one Claude turn, all three tool calls fire in parallel. The WS captures most lifecycle events; the REST order_info call provides the authoritative final state in case any early events were missed.

Note: This server does NOT include order placement — you'd add a separate trading server (or place manually on Bitkub) for the place step. The watch + verify pattern still works against an order placed by other means.

Combined workflows (multiple tools in one prompt)

Security

• Read-only by design. This server intentionally does NOT implement order placement, order cancellation, withdrawal initiation, or address generation. Only data-retrieval endpoints are exposed.
• Use a read-only Bitkub API key. Bitkub's API-key permission model lets you scope a key to read-only operations — please do that. The server will refuse nothing on its own, but a least-privilege key gives you a hard guarantee at the exchange level even if anything misbehaves.
• Credentials are never accepted as tool arguments. They are read from process.env only, sourced from the MCP client's env block. The LLM cannot see the secret.
• Secrets aren't logged. Diagnostics on stderr only mention whether creds are present, never their values.
• Rotate keys by updating the env block in your client config and restarting the MCP client; no server-code change required.

Notes

• All responses pass Bitkub's JSON through unchanged (no field remapping).
• Bitkub envelope errors (error != 0) are surfaced as MCP tool errors with the original error code.
• HTTP non-2xx is surfaced with the status and response body.
• Diagnostics are written to stderr only — stdout is reserved for the MCP transport.