Bybit Official Trading Server
Bybit trading MCP server β exposes Bybit REST and WebSocket APIs as MCP tools
Ask AI about Bybit Official Trading Server
Powered by Claude Β· Grounded in docs
I know everything about Bybit Official Trading Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
|
Account & Asset
|
User & Sub-Accounts
|
WebSocket Real-Time
|
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_SECRETin 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.peminto the public key field - Save the API Key shown after creation
- Use
BYBIT_API_KEY+BYBIT_API_PRIVATE_KEY_PATH(absolute path tobybit_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_PATHpointing to a PEM file on disk. Required for Self-generated (user-uploaded) RSA key pairs. The server addsX-BAPI-SIGN-TYPE: 2automatically.
Quick rule: chose "System-generated" on Bybit β use HMAC. Chose "Self-generated" β use RSA.
If both
BYBIT_API_SECRETandBYBIT_API_PRIVATE_KEY_PATHare 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. RemoveBYBIT_API_SECRETto 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_SECRETandBYBIT_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 |
pre-upgrade | Yes | 6 | Pre-upgrade order history, execution list, closed PnL, transaction log, delivery and settlement records |
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 |
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: 248 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 (viaBYBIT_API_PRIVATE_KEY_PATH) per Bybit's V5 API specification - For RSA mode, store the PEM file with
chmod 600and 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
