Trading

Bybit MCP Server

A production-ready MCP server for Bybit — 396 tools covering market data, trading, positions, account management, assets, loans, earn products, referral queries, tax reports, and real-time WebSocket streams

Quick Start • Features • Configuration • Tools Reference • Troubleshooting • Contributing

中文文档

Overview

Bybit MCP Server enables AI assistants like Claude, Cursor, VS Code, and other MCP-compatible clients to interact directly with the Bybit cryptocurrency exchange. Query live market data, manage your account, and monitor real-time streams — all through natural language.

Why Bybit MCP?

• Complete V5 Coverage — 396 tools across market data, trading, positions, account, asset, loans, earn, referrals, tax reports, copy trading, WebSocket, and WS-trade categories
• Referral Queries — View campaign reward rules, your referral identity, invitations, and commission records
• Strategy Trading — POV for spot and derivatives with required quantity or value limits, Iceberg splitting into up to 200 child orders
• Secure by Design — API credentials are read from environment variables at runtime, never hardcoded
• Read-Only Mode — All 23 market data tools work without any API key
• Real-Time Streams — 27 WebSocket tools for live orderbook, tickers, positions, and more
• Zero-Install Start — Run instantly with npx bybit-official-trading-server@latest
• Universal Compatibility — Works with Claude Desktop, Cursor, VS Code, and any MCP client

POV execution requires a 5–3600 second interval and a positive quantity or value limit. A duration may add a time limit; it cannot replace the quantity or value limit. OneTime execution is unavailable through MCP because the API ignores those limits in that mode.

Features

Market Data

• Option Markets — Discover option underlyings and filter by asset type
• Prices & Tickers — Real-time spot and derivatives prices
• Orderbook — Configurable depth snapshots
• Klines — Historical OHLCV candlestick data
• Funding Rates — Current and historical rates
• Open Interest — Long/short ratio, ADL indicators
• Risk Limits — Volatility index, delivery prices, insurance pool

Account & Asset

• Wallet Balance — Unified account overview
• Transaction Log — Full trade and funding history
• Fee Rates — Maker/taker rates by instrument
• Collateral — Settings, Greeks, MMP state
• Asset Overview — Portfolio margin, delivery/settlement records
• Multi-Account — Aggregated parent and sub-account assets
• Tax Reports — Create, track, download, and batch-query tax report export tasks

User & Sub-Accounts

• API Key Info — Permissions, VIP level, rate limits
• Sub-Account Management — List and query sub-accounts
• Member Types — Account type queries per member
• Referral & Affiliate — Campaign rewards, identity, invitations, and commission queries

WebSocket Real-Time

• Public Streams — Orderbook, tickers, klines, trades, liquidations
• Private Streams — Executions, positions, wallet updates
• Options — Greeks snapshots
• Block Trading — RFQ updates
• Spread Trading — Spread instrument streams
• Snapshot Model — Single-call, no persistent connections needed

Quick Start

Step 1 — Get your Bybit API credentials (skip if you only need market data)

Option A — HMAC-SHA256 (standard, recommended for most users)

1. Log in to Bybit and go to Account & Security → API Management
2. Click Create New Key, select System-generated API Key
3. Set the permissions you need (read-only is recommended for safety)
4. Save the API Key and API Secret — the secret is shown only once
5. Use BYBIT_API_KEY + BYBIT_API_SECRET in your config

Option B — RSA-SHA256 (self-generated key pair)

1. Generate an RSA key pair locally:

   openssl genrsa -out bybit_private.pem 2048
   openssl rsa -in bybit_private.pem -pubout -out bybit_public.pem
   chmod 600 bybit_private.pem
   

2. Log in to Bybit and go to Account & Security → API Management
3. Click Create New Key, select Self-generated API Key
4. Paste the contents of bybit_public.pem into the public key field
5. Save the API Key shown after creation
6. Use BYBIT_API_KEY + BYBIT_API_PRIVATE_KEY_PATH (absolute path to bybit_private.pem) in your config

Step 2 — Connect to your AI assistant

Choose the section below that matches your tool (Claude Desktop, Cursor, or VS Code).

Step 3 — Verify the connection

After configuring, restart your AI assistant and ask:

"What's the current BTCUSDT price?"

If you get a live price back, the server is connected and working.

Step 4 — Let the AI learn the full capability in one prompt (optional but recommended)

Paste the following into your AI assistant to have it read the official documentation and start helping you trade:

Please read https://raw.githubusercontent.com/bybit-exchange/trading-mcp/main/README.md save it as a mcp, and help me trade on Bybit.

The AI will read the README, understand all available tools, and be ready to assist with market data queries, account management, and more.

Configuration Reference

Market data tools work without credentials. Authenticated tools require BYBIT_API_KEY plus exactly one signing credential:

• HMAC-SHA256 (default) — set BYBIT_API_SECRET. Works with System-generated API keys.
• RSA-SHA256 — set BYBIT_API_PRIVATE_KEY_PATH pointing to a PEM file on disk. Required for Self-generated (user-uploaded) RSA key pairs. The server adds X-BAPI-SIGN-TYPE: 2 automatically.

Quick rule: chose "System-generated" on Bybit → use HMAC. Chose "Self-generated" → use RSA.

If both BYBIT_API_SECRET and BYBIT_API_PRIVATE_KEY_PATH are set (e.g. a system-level env var conflicts with your MCP config), RSA takes precedence and a warning is printed to the server log. Remove BYBIT_API_SECRET to suppress the warning.

Usage with Claude Desktop

First-time setup: Claude Desktop may offer "Always allow" for tool access. Each write operation still requires a separate approval form. Use a trusted MCP client: the server relies on its approval response.

1. Find your config file

Open the file in any text editor (create it if it doesn't exist).

2. Add the MCP server config

HMAC mode (System-generated API key):

{
  "mcpServers": {
    "bybit": {
      "command": "npx",
      "args": ["-y", "bybit-official-trading-server@latest"],
      "env": {
        "BYBIT_API_KEY": "your_api_key",
        "BYBIT_API_SECRET": "your_api_secret"
      }
    }
  }
}

RSA mode (Self-generated API key):

{
  "mcpServers": {
    "bybit": {
      "command": "npx",
      "args": ["-y", "bybit-official-trading-server@latest"],
      "env": {
        "BYBIT_API_KEY": "your_api_key",
        "BYBIT_API_PRIVATE_KEY_PATH": "/absolute/path/to/bybit_private.pem"
      }
    }
  }
}

Replace the values with your actual Bybit credentials. Use one signing mode only — do not set both BYBIT_API_SECRET and BYBIT_API_PRIVATE_KEY_PATH. If the file already has other MCP servers, add the "bybit" block inside the existing "mcpServers" object.

3. Restart Claude Desktop

Quit and reopen Claude Desktop. The Bybit tools will be available automatically on next launch.

For testnet:

{
  "mcpServers": {
    "bybit": {
      "command": "npx",
      "args": ["-y", "bybit-official-trading-server@latest"],
      "env": {
        "BYBIT_API_KEY": "your_testnet_api_key",
        "BYBIT_API_SECRET": "your_testnet_api_secret",
        "BYBIT_TESTNET": "true"
      }
    }
  }
}

Usage with Cursor

1. Find your config file

Create the file if it doesn't exist.

2. Add the MCP server config

HMAC mode (System-generated API key):

{
  "mcpServers": {
    "bybit": {
      "command": "npx",
      "args": ["-y", "bybit-official-trading-server@latest"],
      "env": {
        "BYBIT_API_KEY": "your_api_key",
        "BYBIT_API_SECRET": "your_api_secret"
      }
    }
  }
}

RSA mode (Self-generated API key):

{
  "mcpServers": {
    "bybit": {
      "command": "npx",
      "args": ["-y", "bybit-official-trading-server@latest"],
      "env": {
        "BYBIT_API_KEY": "your_api_key",
        "BYBIT_API_PRIVATE_KEY_PATH": "/absolute/path/to/bybit_private.pem"
      }
    }
  }
}

3. Restart Cursor

After saving the file, restart Cursor. The Bybit MCP server will be listed under Settings → MCP.

Usage with VS Code

1. Find or create your MCP config

In your project root (or workspace), create .vscode/mcp.json.

HMAC mode (System-generated API key):

{
  "servers": {
    "bybit": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bybit-official-trading-server@latest"],
      "env": {
        "BYBIT_API_KEY": "your_api_key",
        "BYBIT_API_SECRET": "your_api_secret"
      }
    }
  }
}

RSA mode (Self-generated API key):

{
  "servers": {
    "bybit": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bybit-official-trading-server@latest"],
      "env": {
        "BYBIT_API_KEY": "your_api_key",
        "BYBIT_API_PRIVATE_KEY_PATH": "/absolute/path/to/bybit_private.pem"
      }
    }
  }
}

2. Enable MCP in VS Code settings

Open VS Code Settings (Cmd+, / Ctrl+,), search for mcp, and ensure MCP support is enabled for your AI extension (e.g. GitHub Copilot).

3. Reload the window

Run Developer: Reload Window from the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) to pick up the new config.

Available Tool Categories

Total: 396 tools

Example Prompts

Once connected to an AI assistant, you can use natural language:

Market data:

• "What is the current BTC/USDT price?"
• "Show me the order book for ETHUSDT with depth 50"
• "Get the last 10 BTC perpetual klines on the 1-hour interval"
• "What are the current funding rates for the top 5 perpetual contracts?"
• "What's the open interest for BTCUSDT?"

Account & Asset:

• "What's my wallet balance?"
• "Show me my recent transaction log"
• "What are my maker/taker fee rates?"
• "Show me my total assets across all sub-accounts"
• "What's my portfolio margin status?"

User & Sub-accounts:

• "List all my sub-accounts"
• "Show me the permissions and VIP level of my current API key"
• "What account types do my sub-accounts use?"
• "Who have I invited through the referral program?"

WebSocket / Real-time:

• "Subscribe to the BTCUSDT orderbook and give me a snapshot"
• "Get the latest execution records from my account"
• "What are my current open positions?"

WebSocket Pattern Details

WebSocket tools are compatible with MCP's request/response model:

1. The tool opens a WebSocket connection to Bybit's streaming endpoint
2. Subscribes to the requested channel (with auth handshake for private channels)
3. Collects the specified number of messages (default: 1) or waits up to timeoutMs (default: 5000 ms)
4. Returns the collected snapshot and closes the connection

This makes real-time data accessible in a single tool call without managing persistent connections.

Security Notes

• API keys are read from environment variables at call time, never hardcoded
• Two signing modes are supported: HMAC-SHA256 (default, via BYBIT_API_SECRET) and RSA-SHA256 (via BYBIT_API_PRIVATE_KEY_PATH) per Bybit's V5 API specification
• For RSA mode, store the PEM file with chmod 600 and never commit it to source control
• Never share your API secret or commit it to source control
• Use API keys with minimal required permissions (read-only where possible)

Troubleshooting

MCP Server Not Loading / "No MCP servers configured"

If you've configured the server but your AI assistant shows no tools or "No MCP servers configured":

1. Check the correct configuration file

Claude Code reads MCP server config from ~/.claude.json (per-project), not from ~/.claude/settings.json. The recommended way to add the server is via CLI:

claude mcp add bybit -- npx -y bybit-official-trading-server@latest

This writes the config to the correct location.

2. Use the full path to node / npx if needed

Some environments spawn subprocesses without loading your shell profile (.zshrc / .zprofile), so PATH may not include the Node.js bin directory. Find the full path and use it explicitly:

# Find your npx path
which npx
# Example: /usr/local/bin/npx

3. Restart your AI assistant after configuration changes

MCP servers connect at session startup. After adding or changing config, you must exit and restart your AI assistant for changes to take effect.

4. Verify the server starts correctly

Test that the server can start and respond to MCP protocol:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | npx -y bybit-official-trading-server@latest

5. Don't run the server manually

Your AI client manages the MCP server process itself via stdio. A manually started server instance is completely separate — the client won't connect to it. Let the client handle the lifecycle automatically.

Quick Diagnosis Checklist

Local Development

# Install dependencies
npm install

# Start the server in development mode
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

Risk Warning

Cryptocurrency trading involves substantial risk of loss. Please read the following before use:

• Protect Your API Credentials — Use IP allowlists and grant only the minimum permissions required; disable withdrawal access unless explicitly needed
• Test Before You Trade — Validate your setup on Bybit Testnet before connecting to your live account (set BYBIT_TESTNET=true)
• You Are in Control — All actions are initiated by you or your AI assistant; review orders carefully before execution
• Bybit Terms Apply — Use of this server is subject to Bybit's Terms of Service

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Resources

License

MIT