README.md•6.77 kB
# 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:**
```bash
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:
```bash
# 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:
```bash
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
```bash
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)
```bash
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:
```bash
cd /Users/rkondis/personalwork/mcp-bybit-node
node test-mcp.js
```
### Test trade execution:
```bash
cd /Users/rkondis/personalwork/mcp-bybit-node
node test-order.js
```
## Usage Examples
### Validate order before placing:
```javascript
// 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:
```javascript
// Place market buy order for ETHUSDT
place_order("linear", "ETHUSDT", "Buy", "Market", "0.02", positionIdx="0")
```
### Calculate position size with risk management:
```javascript
// 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:
```javascript
// 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:
```javascript
// 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:
```javascript
// Set 10x leverage for ETHUSDT
set_leverage("linear", "ETHUSDT", "10", "10")
```
### Check positions:
```javascript
// 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:**
```bash
ls -la /Users/rkondis/personalwork/mcp-bybit-node/dist/index.js
# Should show: -rwxr-xr-x (executable)
```
2. **Test server directly:**
```bash
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:**
```bash
cat /Users/rkondis/personalwork/mcp-bybit-node/.env
```
4. **Use the startup script:**
```bash
/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.