Bybit MCP Server (Node.js)
A Model Context Protocol (MCP) server for Bybit trading operations, built with Node.js and TypeScript.
Features
- ✅ Perfect Authentication - Uses exact Cloud Functions signature logic
- ✅ Smart Position Validation - Automatic validation against Bybit trading rules
- ✅ Position Mode Detection - Automatically detects one-way vs hedge mode
- ✅ 16 Trading Tools - Complete market data, account, and trading operations
- ✅ Demo Mode Support - Safe testing environment
Installation
- Build the server:
cd /Users/rkondis/personalwork/mcp-bybit-node
npm install
npm run build
- Configure environment:
- Copy
.env file with your Bybit API credentials - Set
DEMO=true for safe testing
Claude MCP Integration
Method 1: Using the startup script (Recommended)
Step 1: Ensure your .env file exists with your API keys:
# Check if .env file exists
ls -la /Users/rkondis/personalwork/mcp-bybit-node/.env
# If it doesn't exist, create it:
cat > /Users/rkondis/personalwork/mcp-bybit-node/.env << EOF
ACCESS_KEY=your_access_key_here
SECRET_KEY=your_secret_key_here
DEMO=true
EOF
Step 2: Add to Claude MCP:
claude mcp add-json bybit-node '{
"type": "stdio",
"command": "/Users/rkondis/personalwork/mcp-bybit-node/start-server.sh",
"args": []
}'
The startup script automatically loads API keys from the .env file.
Method 2: Direct node execution with environment variables
claude mcp add-json bybit-node '{
"type": "stdio",
"command": "node",
"args": ["/Users/rkondis/personalwork/mcp-bybit-node/dist/index.js"],
"env": {
"ACCESS_KEY": "your_access_key_here",
"SECRET_KEY": "your_secret_key_here",
"DEMO": "true"
}
}'
Method 3: Using working directory (reads .env automatically)
claude mcp add-json bybit-node '{
"type": "stdio",
"command": "node",
"args": ["dist/index.js"],
"cwd": "/Users/rkondis/personalwork/mcp-bybit-node",
"env": {
"DEMO": "true"
}
}'
This method uses the existing .env file in the working directory.
- Market Data:
get_tickers - Get ticker informationget_orderbook - Get orderbook dataget_kline - Get K-line (candlestick) dataget_instruments_info - Get exchange information
- Account Management:
get_wallet_balance - Get wallet balanceget_positions - Get position informationget_api_key_information - Get API key information
- Trading Operations:
validate_order_quantity - Validate order quantity against trading rulescalculate_position_size - Calculate optimal position size based on risk managementcalculate_trailing_stop - Calculate trailing stop loss with breakeven and profit protectiondetect_position_mode - Detect position mode and get recommended positionIdxplace_order - Execute order with automatic position mode detectionplace_order_with_trailing_stop - Place order with built-in trailing stop losscancel_order - Cancel orderget_order_history - Get order historyget_open_orders - Get open orders
- Position Management:
set_leverage - Set leverage for a specific symbolset_trading_stop - Set trading stopset_margin_mode - Set margin mode
- Utility:
get_access_key - Get access key from environmentget_secret_key - Get secret key from environment
Testing
Test the MCP server:
cd /Users/rkondis/personalwork/mcp-bybit-node
node test-mcp.js
Test trade execution:
cd /Users/rkondis/personalwork/mcp-bybit-node
node test-order.js
Usage Examples
Validate order before placing:
// Check if $80 worth of ETHUSDT is valid
validate_order_quantity("linear", "ETHUSDT", 80)
// Returns: { validatedQty: "0.02", estimatedCost: "73.18", adjustments: [] }
Place a validated order:
// Place market buy order for ETHUSDT
place_order("linear", "ETHUSDT", "Buy", "Market", "0.02", positionIdx="0")
Calculate position size with risk management:
// Calculate position size for 2% risk with $1000 balance
calculate_position_size("linear", "ETHUSDT", 1000, 2, 3500, 3600, 10)
// Returns: {
// recommendedQty: "0.57",
// riskAmount: 20,
// positionValue: 2052,
// takeProfitSuggestion: 3800,
// warnings: []
// }
Calculate trailing stop loss with profit protection:
// Calculate trailing stop for a long position
calculate_trailing_stop("linear", "ETHUSDT", 3600, 3750, "Buy", 3500, 50)
// Returns: {
// newStopLoss: 3700,
// trailingActivated: true,
// breakevenProtection: true,
// profitProtected: 0,
// recommendations: {
// shouldUpdateStop: true,
// protectionLevel: "breakeven",
// reasoning: "Breakeven protection activated - stop moved to entry price"
// }
// }
Place order with trailing stop loss:
// Place market buy order with 50 USDT trailing stop
place_order_with_trailing_stop("linear", "ETHUSDT", "Buy", "Market", "0.02", null, "50")
// Returns: Order placed with automatic trailing stop that follows price movement
Set leverage:
// Set 10x leverage for ETHUSDT
set_leverage("linear", "ETHUSDT", "10", "10")
Check positions:
// Get all linear positions
get_positions("linear")
Key Improvements Over Python Version
- ✅ No signature errors - Perfect authentication with Bybit API
- ✅ Smart validation - Automatic position size and mode validation
- ✅ Better error handling - Comprehensive error messages and recovery
- ✅ TypeScript support - Full type safety and IntelliSense
Troubleshooting
If Claude MCP fails to start:
- Check file permissions:
ls -la /Users/rkondis/personalwork/mcp-bybit-node/dist/index.js
# Should show: -rwxr-xr-x (executable)
- Test server directly:
cd /Users/rkondis/personalwork/mcp-bybit-node
node dist/index.js
# Should show: "Bybit MCP Server (Node.js) running on stdio"
- Check environment variables:
cat /Users/rkondis/personalwork/mcp-bybit-node/.env
- Use the startup script:
/Users/rkondis/personalwork/mcp-bybit-node/start-server.sh
Security Notes
- Always use
DEMO=true for testing - Never commit API keys to version control
- Use environment variables for sensitive data
- Test thoroughly in demo mode before production use
Support
The server includes comprehensive logging and error handling. Check the console output for detailed information about any issues.