Bybit MCP Server

A production-ready MCP server for Bybit — 206 tools covering market data, trading, positions, account management, assets, 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 — 206 tools across market data, trading, positions, account, asset, user, WebSocket, and WS-trade categories
Secure by Design — API credentials are read from environment variables at runtime, never hardcoded
Read-Only Mode — All 22 market data tools work without any API key
Real-Time Streams — 26 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

Features

Market Data 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
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 — Invitation and referral 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)

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

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

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

Log in to Bybit and go to Account & Security → API Management
Click Create New Key, select Self-generated API Key
Paste the contents of bybit_public.pem into the public key field
Save the API Key shown after creation
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

Variable	Required	Default	Description
`BYBIT_API_KEY`	For auth endpoints	—	Your Bybit API key
`BYBIT_API_SECRET`	HMAC mode	—	Your Bybit API secret (HMAC-SHA256 signing)
`BYBIT_API_PRIVATE_KEY_PATH`	RSA mode	—	Absolute path to your RSA private key PEM file (RSA-SHA256 signing)
`BYBIT_TESTNET`	No	`false`	Set to `true` to use the testnet

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 will show an authorization prompt the first time each tool is called. Click "Always allow" to permanently approve it — you won't be asked again.

1. Find your config file

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

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

Platform	Path
macOS / Linux	`~/.cursor/mcp.json`
Windows	`%USERPROFILE%\.cursor\mcp.json`

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

Category	Auth	Tools	Description
`market`	No	22	Klines, orderbook, tickers, funding rates, open interest, volatility, risk limits, long/short ratio, delivery price, insurance pool, and more
`account`	Yes	18	Wallet balance, transaction log, fee rates, margin mode, collateral switch, hedging mode, price limit, MMP modify and reset, option Greeks, DCP config, SMP group, account instruments, and more
`trade`	Yes	12	Create, amend, cancel orders, batch order operations, open orders, order history, spot borrow quota, DCP, and order pre-check
`rfq-trading`	Yes	15	Create/cancel RFQs and quotes, execute quotes, accept non-LP quotes, RFQ config, realtime and historical RFQs/quotes, trade history, public trades
`position`	Yes	11	Position list, leverage, position mode, trading stop, auto-add margin, add/reduce margin, closed PnL, closed positions, move positions, and risk limit confirmation
`asset`	Yes	5	Asset overview, portfolio margin, delivery/settlement records, aggregated parent+sub account assets
`user`	Yes	16	API key info & permissions, sub-account listing and management, create/update/delete API keys, freeze sub-accounts, delete sub-accounts, sign agreement, member account types, referral/invitation queries
`spread-trading`	Mixed	12	Spread instruments, orderbook, tickers, recent trades, create/amend/cancel spread orders, open orders, order history, trade history, max order quantity
`bot`	Yes	18	Futures combo bot, futures grid bot, futures martingale bot, spot grid bot, spot DCA bot — create, close, detail, validate, and parameter limits
`copy-trading-classic`	Yes	2	Classic copy trading: recommended leader leaderboard, create follower binding
`copy-trading-tradfi`	Yes	2	TradFi copy trading (MT5): recommended provider leaderboard, create follower binding
`strategy`	Yes	6	TWAP, Chase Limit, Iceberg strategy orders — create, list, sub-order list, stop
`earn`	Mixed	8	Earn product queries, stake/redeem orders, order history, positions, yield history, hourly yield, APR history, position modify
`advanceearn`	Mixed	5	Advance Earn: product queries, place order, positions, order history, product extra info
`smartleverage`	Yes	1	Smart Leverage: redeem estimation amount list
`doublewin`	Yes	1	Double Win: leverage and expiry queries
`fixedterm`	Mixed	6	Fixed-term deposits: product list, place/redeem orders, positions, order history, auto-invest settings
`earntoken`	Mixed	7	Token earn products: place orders, positions, order history, daily/hourly yield, historical APR
`liquiditymining`	Yes	10	Liquidity mining: add/remove/reinvest liquidity, add margin, claim interest, positions, orders, yield records, liquidation records
`p2p`	Yes	13	P2P ad management and order queries: create/update/remove ads, browse online ads, query personal ads and details, order list, order detail, pending orders, mark order as paid, chat messages, counterparty info, payment methods
`card`	Yes	1	Bybit Card asset (transaction) records: paginated query with status, last-four card digits, merchant, query type, transaction/order ID, card token, and time-range filters
`alpha`	Yes	10	On-chain trading: trade quote, purchase, redeem, pay token list, order list, token list, token prices, token details, asset list, asset detail
`websocket`	Mixed	26	Real-time snapshots via subscribe-snapshot pattern: orderbook, tickers, klines, trades, liquidations, executions, positions, wallet, option Greeks, RFQ block trades, spread trading
`wstrade`	Yes	6	WebSocket trade operations via /v5/trade: place order, cancel order, amend order, batch place, batch cancel, batch amend

Total: 243 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:

The tool opens a WebSocket connection to Bybit's streaming endpoint
Subscribes to the requested channel (with auth handshake for private channels)
Collects the specified number of messages (default: 1) or waits up to timeoutMs (default: 5000 ms)
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

Symptom	Cause	Fix
No tools shown after config	Config in wrong file	Use `claude mcp add` CLI command
Config exists but tools don't load	`npx` / `node` not found in PATH	Use absolute path to `npx`
Tools loaded before but not now	Session not restarted after config change	Restart your AI assistant
Authentication errors	Missing or incorrect API credentials	Check `BYBIT_API_KEY` and `BYBIT_API_SECRET` (HMAC) or `BYBIT_API_PRIVATE_KEY_PATH` (RSA)

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.

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

Resources

Resource	Description
Bybit V5 API Docs	Official Bybit API documentation
Bybit Testnet	Practice trading with test funds
MCP Specification	Model Context Protocol spec
npm Package	Published npm package

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh.md		README.zh.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

Bybit MCP Server

Overview

Why Bybit MCP?

Features

Market Data

Account & Asset

User & Sub-Accounts

WebSocket Real-Time

Quick Start

Configuration Reference

Usage with Claude Desktop

Usage with Cursor

Usage with VS Code

Available Tool Categories

Example Prompts

WebSocket Pattern Details

Security Notes

Troubleshooting

MCP Server Not Loading / "No MCP servers configured"

1. Check the correct configuration file

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

3. Restart your AI assistant after configuration changes

4. Verify the server starts correctly

5. Don't run the server manually

Quick Diagnosis Checklist

Local Development

Risk Warning

Contributing

Resources

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

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

Packages