falconiun/bybit-mcp repository overview

⁠Bybit MCP Server

A Model Context Protocol (MCP) server that provides access to Bybit's v5 Market API endpoints. This server enables AI assistants to fetch real-time market data, instrument information, and trading statistics from the Bybit cryptocurrency exchange.

⁠Features

⁠Core Market Data

• Server Time: Get current Bybit server time
• Tickers: Retrieve ticker information for trading symbols
• Order Book: Get order book depth for any symbol
• Recent Trades: Access recent trade history

⁠Kline/Candlestick Data

• Standard Klines: Get OHLCV candlestick data
• Mark Price Klines: Get mark price historical data
• Index Price Klines: Get index price historical data
• Premium Index Klines: Get premium index price data

⁠Trading Information

• Instruments Info: Get detailed trading instrument information
• Funding Rate History: Access historical funding rates
• Open Interest: Get open interest statistics
• Risk Limits: Retrieve risk limit information

⁠Market Statistics

• Insurance Fund: Get insurance fund data
• Long/Short Ratio: Access long/short ratio statistics

⁠Trading Operations (Requires BYBIT_TRADING_ENABLED=true)

• Order Management: Place, amend, and cancel orders
• Batch Operations: Execute multiple orders in a single request
• Order History: View open/closed orders and trade history
• Order Types: Support for Market, Limit, and conditional orders

⁠Position Management (Requires BYBIT_TRADING_ENABLED=true)

• Position Info: Query real-time position data
• Leverage Control: Set and modify position leverage
• Margin Management: Switch between cross/isolated margin modes
• Trading Stops: Set take profit, stop loss, and trailing stops
• Auto Add Margin: Configure automatic margin addition
• Position Modes: Switch between one-way and hedge position modes
• P&L Tracking: Access closed profit and loss records

⁠Supported Categories

• Linear: USDT perpetual, USDC perpetual, USDC futures
• Inverse: Inverse perpetual, Inverse futures
• Option: Options trading
• Spot: Spot trading pairs

⁠Docker Usage

⁠Build and Run

# Build the Docker image
docker build -t bybit-mcp .

# Run with environment variables
docker run -i --rm \
  -e BYBIT_API_KEY=your_api_key \
  -e BYBIT_API_SECRET=your_api_secret \
  -e BYBIT_TESTNET=false \  # Set to true for testnet
  -e BYBIT_TRADING_ENABLED=false \  # Set to true to enable trading
  bybit-mcp

⁠Using Docker Compose

# Set environment variables in .env file first
docker-compose up

⁠Configuration

⁠Environment Variables

• BYBIT_API_KEY: Your Bybit API key
• BYBIT_API_SECRET: Your Bybit API secret
• BYBIT_TESTNET: Set to true to use the Bybit testnet (default is false)
• BYBIT_TRADING_ENABLED: Set to true to enable trading operations (default is false)

⁠Safety Controls

The server implements several safety controls for trading operations:

⁠Trading Disabled by Default

• All trading and position management tools are disabled by default
• Must explicitly set BYBIT_TRADING_ENABLED=true to enable trading
• Market data tools are always available regardless of this setting

⁠Testnet Support

• Set BYBIT_TESTNET=true to use Bybit's testnet environment
• Recommended for development and testing
• Testnet trading uses fake money and won't affect real balances

⁠Tool Visibility

• Trading tools only appear in the tool list when BYBIT_TRADING_ENABLED=true
• Position management tools require the same flag
• This prevents accidental trading operations

⁠API Permissions

Ensure your Bybit API key has the appropriate permissions:

• Read-only: For market data (always safe)
• Trade: Required for order operations (enable only when needed)
• Position: Required for position management
• Withdraw: Not required for this server

⁠VS Code MCP Integration

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "bybit-mcp": {
        "type": "stdio",
        "command": "uv",
        "args": ["run","-i", "bybit-mcp"],
        "env": {
          "BYBIT_API_KEY": "${input:bybit_api_key}",
          "BYBIT_API_SECRET": "${input:bybit_api_secret}",
          "BYBIT_TESTNET": "false",
          "BYBIT_TRADING_ENABLED": "false"
        }
      }
    },
    "inputs": [
      {
        "type": "promptString",
        "id": "bybit_api_key",
        "description": "Bybit API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "bybit_api_secret",
        "description": "Bybit API Secret",
        "password": true
      },
      {
        "type": "promptString",
        "id": "bybit_testnet",
        "description": "Use Bybit Testnet (true/false)",
        "default": "false"
      },
      {
        "type": "promptString",
        "id": "bybit_trading_enabled",
        "description": "Enable Trading Operations (true/false)",
        "default": "false"
      }
    ]
  }
}

⁠Testing

⁠MCP Inspector

Test the server using the MCP inspector:

npx @modelcontextprotocol/inspector uv run bybit-mcp

⁠Unit Tests

uv run pytest tests/

⁠API Reference

⁠Market Data Tools

All market data tools are always available and do not require special permissions.

⁠Core Data

• get_server_time: Get current Bybit server time
• get_tickers: Get ticker information for symbols
• get_order_book: Get order book depth
• get_recent_trades: Get recent trade history

⁠Kline/Candlestick Data

• get_kline: Get standard OHLCV kline data
• get_mark_price_kline: Get mark price historical data
• get_index_price_kline: Get index price historical data
• get_premium_index_price_kline: Get premium index kline data

⁠Market Information

• get_instruments_info: Get trading instrument details
• get_funding_rate_history: Get funding rate history
• get_open_interest: Get open interest statistics
• get_insurance: Get insurance fund data
• get_risk_limit: Get risk limit information
• get_long_short_ratio: Get long/short ratio data

⁠Trading Tools (Requires BYBIT_TRADING_ENABLED=true)

These tools are only available when trading is enabled via the BYBIT_TRADING_ENABLED environment variable.

⁠Order Management

• place_order: Place a new order (Market, Limit, etc.)
• amend_order: Modify an existing order
• cancel_order: Cancel a specific order
• cancel_all_orders: Cancel all open orders

⁠Batch Operations

• batch_place_order: Place multiple orders in one request
• batch_amend_order: Amend multiple orders in one request
• batch_cancel_order: Cancel multiple orders in one request

⁠Order Information

• get_open_closed_orders: Get open and closed orders
• get_order_history: Get order history
• get_trade_history: Get trade execution history

⁠Position Tools (Requires BYBIT_TRADING_ENABLED=true)

Position management tools require trading to be enabled.

⁠Position Information

• get_position_info: Query real-time position data
• get_closed_pnl: Get closed profit and loss records

⁠Position Configuration

• set_leverage: Set position leverage
• switch_cross_isolated_margin: Switch margin mode
• switch_position_mode: Switch between one-way/hedge mode
• set_auto_add_margin: Configure automatic margin addition

⁠Risk Management

• set_trading_stop: Set take profit, stop loss, trailing stops
• modify_position_margin: Add or reduce position margin

⁠Tools

All tools support the following common parameters where applicable:

• category: Product type (linear, inverse, option, spot)
• symbol: Trading symbol (e.g., BTCUSDT)
• limit: Data size limit per page
• start/end: Time range for historical data