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

1. Build the server:

   cd /Users/rkondis/personalwork/mcp-bybit-node
   npm install
   npm run build
   

2. 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.

Available Tools

1. Market Data:

   • get_tickers - Get ticker information
   • get_orderbook - Get orderbook data
   • get_kline - Get K-line (candlestick) data
   • get_instruments_info - Get exchange information

2. Account Management:

   • get_wallet_balance - Get wallet balance
   • get_positions - Get position information
   • get_api_key_information - Get API key information

3. Trading Operations:

   • validate_order_quantity - Validate order quantity against trading rules
   • calculate_position_size - Calculate optimal position size based on risk management
   • calculate_trailing_stop - Calculate trailing stop loss with breakeven and profit protection
   • detect_position_mode - Detect position mode and get recommended positionIdx
   • place_order - Execute order with automatic position mode detection
   • place_order_with_trailing_stop - Place order with built-in trailing stop loss
   • cancel_order - Cancel order
   • get_order_history - Get order history
   • get_open_orders - Get open orders

4. Position Management:

   • set_leverage - Set leverage for a specific symbol
   • set_trading_stop - Set trading stop
   • set_margin_mode - Set margin mode

5. Utility:

   • get_access_key - Get access key from environment
   • get_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:

1. Check file permissions:

   ls -la /Users/rkondis/personalwork/mcp-bybit-node/dist/index.js
   # Should show: -rwxr-xr-x (executable)
   

2. Test server directly:

   cd /Users/rkondis/personalwork/mcp-bybit-node
   node dist/index.js
   # Should show: "Bybit MCP Server (Node.js) running on stdio"
   

3. Check environment variables:

   cat /Users/rkondis/personalwork/mcp-bybit-node/.env
   

4. 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.