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