MCP server

The WhiteBIT MCP server exposes the full WhiteBIT API as AI tools over the Model Context Protocol. Connect a supported AI client and interact with markets, trading, balances, wallets, and sub-accounts using natural language.

115 tools across market data, spot trading, collateral trading, wallet, lending, sub-accounts, mining pool, and currency conversion
Runs locally — API keys never leave the machine
Credentials are passed per tool call and are not stored or logged by the server

The MCP server documented on this page enables trading via AI clients. For documentation search via MCP (searching the WhiteBIT API docs in Cursor or VS Code), see Docs search via MCP.

Prerequisites

A WhiteBIT account with an API key (for trading tools) — see API key generation
A supported AI client: Claude Code, Cursor, Claude Desktop, Codex, or OpenClaw
uv or Docker

Quick start

Auto-setup (recommended)
Docker
Without Docker

One command configures the MCP server for every supported AI client at once. No Docker, no manual config editing.

Install uv

uv is a Python package manager that provides the uvx command used to run the server.

macOS / Linux
Windows

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Run the setup command

uvx whitebit-mcp-setup --public=YOUR_API_KEY --secret=YOUR_SECRET_KEY

The script writes the server configuration and credentials into the config of each AI tool it finds:

AI tool	Config file
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\…` (Windows)
Claude Code	`~/.claude/mcp.json`
Cursor	`~/.cursor/mcp.json`
OpenAI Codex	`~/.codex/config.toml`
OpenClaw	`~/.openclaw/openclaw.json`

Existing configs are updated in place — other MCP servers you have configured are not affected.

Start the MCP server

The MCP server is started automatically by your AI client — there is no separate server process to run manually. Under the hood, the setup command registered the following as the server entry in each config:

uvx whitebit-mcp

Your AI client will execute this command on startup and keep the server running in the background as long as the client is open.

Restart your AI client

Restart the AI client so it picks up the new config and launches the server.

Claude Desktop — quit and reopen the app
Claude Code — run claude mcp list to reload, or start a new session
Cursor — open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run MCP: Reload Servers
Codex — start a new Codex session
OpenClaw — restart the agent

Verify the connection

Ask your AI client something like:

What is the current BTC_USDT price?

If the WhiteBIT MCP server is connected, the AI client will call the tool and return live data.

Clone the repository

git clone https://github.com/whitebit-exchange/whitebit-mcp
cd whitebit-mcp

Start the server

docker compose up -d

The MCP endpoint is available at http://localhost:8080/mcp.

Verify the server is running

docker compose ps

The whitebit-mcp container status shows Up.

Stop the server at any time:

docker compose down

Then follow the Connect an AI client section below to register the server in your AI tool.

pip install mcp whitebit-python-sdk
mcp run server.py

The server listens on http://0.0.0.0:8000. Use port 8000 in place of 8080 in all client configurations below.Then follow the Connect an AI client section below to register the server in your AI tool.

Connect an AI client

Skip this section if you used the auto-setup tab above — your AI clients are already configured.

Claude Code
Cursor
Claude Desktop
Codex
OpenClaw

Global registration (all projects):

claude mcp add --transport http --scope user whitebit http://localhost:8080/mcp

Verify the connection:

claude mcp list
# whitebit: http://localhost:8080/mcp (http)

Project-scoped registration:The repository includes a .mcp.json file at the project root. Running claude from inside the cloned whitebit-mcp directory registers the server automatically at project scope.Use /mcp inside a Claude Code session to see live server status and available tools.

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "whitebit": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux) and run MCP: Reload Servers.

Edit the Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whitebit": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Restart Claude Desktop.

Add to ~/.codex/config.toml:

[mcp_servers.whitebit]
url = "http://localhost:8080/mcp"

Start a Codex session — the server connects automatically.

Add to the OpenClaw agent configuration:

{
  "mcp_servers": {
    "whitebit": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

API keys

Generate API keys at whitebit.com → Profile → API Keys. Use the minimum permissions required for the intended use case — read-only keys are sufficient for balance and order queries.

Never paste API keys directly into the AI conversation. Pass credentials as tool parameters at the start of a session. The server uses keys only to sign outgoing WhiteBIT API requests — keys are not stored, logged, or cached.

How credentials work: API keys are passed as parameters in each tool call. The AI client sends the credentials on behalf of the account holder when provided at the start of the conversation. Public market data tools (market info, tickers, order book) query public endpoints. Pass "public" for both api_key and secret_key when only public data is needed.

Example: provide credentials at session start

API key is YOUR_API_KEY and secret is YOUR_SECRET. Show the spot balance.

The AI client passes credentials as tool parameters for the duration of the session.

Example prompts

Market data — no API key required

Pass "public" for both key fields when querying public endpoints.

“What is the current BTC_USDT price?”
“Show the order book for ETH_USDT”
“List all available markets”
“What are the deposit fees for USDT?”
“What is the funding rate history for BTC_USDT?”
“Is WhiteBIT in maintenance mode?”

Spot trading — API key required

“Show the spot balance”
“List open orders on BTC_USDT”
“Place a limit buy order for 0.001 BTC at 90000 on BTC_USDT”
“Cancel all open orders on ETH_USDT”
“Show order history for the last 30 days”

Wallet — API key required

“What is the deposit address for USDT on TRC20?”
“Show recent deposits and withdrawals”
“Transfer 100 USDT from the main account to spot trading”
“Create a WhiteBIT code for 50 USDT”

Collateral trading — API key required

“List open collateral positions”
“Place a collateral limit buy for 0.01 BTC on BTC_USDT”
“What is the current leverage?”
“Close the BTC_USDT position”

Sub-accounts — API key required

“List all sub-accounts”
“Show the balance of sub-account ID 123”
“Transfer 200 USDT to sub-account ID 456”

Configuration reference

Variable	Default	Description
`WHITEBIT_BASE_URL`	`https://whitebit.com`	API base URL — override for custom deployments

Set in docker-compose.yml or as a shell variable:

WHITEBIT_BASE_URL=https://whitebit.com docker compose up

Safe account practices

Before using the MCP server with a live account:

Create a dedicated sub-account with a separate API key for AI tool access.
Fund the sub-account with only the amount allocated for AI-assisted trading.
Generate API keys with the minimum required permissions — use read-only keys for monitoring.
Use IP whitelisting on the API key to restrict access to the machine running the server.
Test with a small amount before executing larger trades.

What’s next

CLI — Trade and query account data directly from the terminal without an AI client
AI tools FAQ — Answers to common questions about API key safety, supported clients, and account practices
AI tools overview — All WhiteBIT AI tools in one place
Authentication — How to generate and manage WhiteBIT API keys
API Reference Overview — Full REST API endpoint listing

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

Prerequisites

Quick start

Connect an AI client

API keys

Example: provide credentials at session start

Example prompts

Market data — no API key required

Spot trading — API key required

Wallet — API key required

Collateral trading — API key required

Sub-accounts — API key required

Configuration reference

Safe account practices

What’s next

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

Documentation Index

​Prerequisites

​Quick start

​Connect an AI client

​API keys

​Example: provide credentials at session start

​Example prompts

​Market data — no API key required

​Spot trading — API key required

​Wallet — API key required

​Collateral trading — API key required

​Sub-accounts — API key required

​Configuration reference

​Safe account practices

​What’s next

Prerequisites

Quick start

Connect an AI client

API keys

Example: provide credentials at session start

Example prompts

Market data — no API key required

Spot trading — API key required

Wallet — API key required

Collateral trading — API key required

Sub-accounts — API key required

Configuration reference

Safe account practices

What’s next