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.

Available Tools

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
Account Management:
- get_wallet_balance - Get wallet balance
- get_positions - Get position information
- get_api_key_information - Get API key information
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
Position Management:
- set_leverage - Set leverage for a specific symbol
- set_trading_stop - Set trading stop
- set_margin_mode - Set margin mode
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:

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.