Bybit Mcp Full

Installation

Installing via Smithery

To install bybit-full-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @BCusack/bybit-full-mcp --client claude

Prerequisites

• Python 3.13+
• uv package manager

Using uvx (Easiest - No Installation Required)

Run directly from GitHub without cloning or installing:

# Set environment variables and run
BYBIT_API_KEY=your_api_key BYBIT_API_SECRET=your_api_secret uvx --from git+https://github.com/your-username/bybit-mcp.git bybit-mcp

Or with all options:

BYBIT_API_KEY=your_api_key \
BYBIT_API_SECRET=your_api_secret \
BYBIT_TESTNET=false \
BYBIT_TRADING_ENABLED=false \
uvx --from git+https://github.com/your-username/bybit-mcp.git bybit-mcp

Note: Replace your-username/bybit-mcp with the actual GitHub repository URL

Using uv (Recommended for Development)

1. Clone the repository:

git clone <repository-url>
cd bybit-mcp

2. Install dependencies:

uv sync

3. Set up environment variables:

# Copy the example environment file
cp .env.example .env

# Edit .env with your Bybit API credentials
BYBIT_API_KEY=your_api_key_here
BYBIT_API_SECRET=your_api_secret_here
BYBIT_TESTNET=false  # Set to true for testnet
BYBIT_TRADING_ENABLED=false  # Set to true to enable trading operations

4. Run the server:

uv run bybit-mcp

Using pip

pip install -e .
python -m bybit_mcp.main

Docker Usage

Build and Run

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

# Run with environment variables (correct syntax)
docker run -i --rm --init \
  -e BYBIT_API_KEY=your_api_key \
  -e BYBIT_API_SECRET=your_api_secret \
  -e BYBIT_TESTNET=false \
  -e BYBIT_TRADING_ENABLED=false \
  bybit-mcp

Using Docker Compose

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

Using Published Image

# Use the published Docker image
docker run -i --rm --init \
  -e BYBIT_API_KEY=your_api_key \
  -e BYBIT_API_SECRET=your_api_secret \
  -e BYBIT_TESTNET=false \
  -e BYBIT_TRADING_ENABLED=false \
  falconiun/bybit-mcp

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

MCP Client Integration

Claude Desktop

To use the Bybit MCP server with Claude Desktop, add the following configuration to your Claude Desktop MCP settings file:

Location of Claude Desktop MCP config:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Using Published Docker Image (Recommended)

{
  "mcpServers": {
    "bybit-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "BYBIT_API_KEY=your_api_key_here",
        "-e", "BYBIT_API_SECRET=your_api_secret_here",
        "-e", "BYBIT_TESTNET=false",
        "-e", "BYBIT_TRADING_ENABLED=false",
        "falconiun/bybit-mcp"
      ]
    }
  }
}

Option 2: Using uvx (No Installation Required)

{
  "mcpServers": {
    "bybit-mcp": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/your-username/bybit-mcp.git",
        "bybit-mcp"
      ],
      "env": {
        "BYBIT_API_KEY": "your_api_key_here",
        "BYBIT_API_SECRET": "your_api_secret_here",
        "BYBIT_TESTNET": "false",
        "BYBIT_TRADING_ENABLED": "false"
      }
    }
  }
}

Option 3: Local Development

{
  "mcpServers": {
    "bybit-mcp": {
      "command": "uv",
      "args": ["run", "bybit-mcp"],
      "cwd": "path/to/your/bybit-mcp",
      "env": {
        "BYBIT_API_KEY": "your_api_key_here",
        "BYBIT_API_SECRET": "your_api_secret_here",
        "BYBIT_TESTNET": "false",
        "BYBIT_TRADING_ENABLED": "false"
      }
    }
  }
}

Important Claude Desktop Notes:

• Replace your_api_key_here and your_api_secret_here with your actual Bybit API credentials
• Set BYBIT_TESTNET=true for testing with fake money (recommended for first use)
• Set BYBIT_TRADING_ENABLED=true only when you want to enable real trading operations
• Restart Claude Desktop after modifying the configuration file

Claude Desktop Usage Examples:

Once configured, you can ask Claude Desktop questions like:

• "What's my USDT balance?"
• "What's the current price of BTCUSDT?"
• "Show me the order book for ETHUSDT"
• "Get me the recent trading history for my account"
• "What positions do I currently have open?"

For trading (when BYBIT_TRADING_ENABLED=true):

• "Place a limit buy order for 0.001 BTC at $95,000"
• "Cancel all my open orders"
• "Set leverage to 10x for BTCUSDT"
• "Set a stop loss at $90,000 for my BTC position"

Security Best Practices:

• Start with BYBIT_TESTNET=true to test functionality safely
• Use API keys with minimal required permissions (read-only for market data, trade permissions only when needed)
• Never share your configuration file containing API keys
• Consider using environment variables for sensitive credentials in production

Other MCP Clients

This server works with any MCP-compatible client. The configuration format may vary slightly between clients, but the core setup remains the same:

VS Code MCP Integration

Option 1: Local Development (Recommended)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "bybit-mcp": {
        "type": "stdio",
        "command": "uv",
        "args": ["run", "bybit-mcp"],
        "cwd": "path/to/bybit-mcp",
        "env": {
          "BYBIT_API_KEY": "${input:bybit_api_key}",
          "BYBIT_API_SECRET": "${input:bybit_api_secret}",
          "BYBIT_TESTNET": "${input:bybit_testnet}",
          "BYBIT_TRADING_ENABLED": "${input:bybit_trading_enabled}"
        }
      }
    },
    "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",
        "default": "false"
      },
      {
        "type": "promptString",
        "id": "bybit_trading_enabled",
        "description": "Enable Bybit Trading",
        "default": "false"
      }
    ]
  }
}

Option 2: Docker (Production)

For using the published Docker image:

{
  "mcp": {
    "servers": {
      "bybit-mcp": {
        "type": "stdio",
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "--init",
          "-e",
          "DOCKER_CONTAINER",
          "-e",
          "BYBIT_API_KEY",
          "-e",
          "BYBIT_API_SECRET",
          "-e",
          "BYBIT_TRADING_ENABLED",
          "-e",
          "BYBIT_TESTNET",
          "falconiun/bybit-mcp"
        ],
        "env": {
          "DOCKER_CONTAINER": "true",
          "BYBIT_API_KEY": "${input:bybit_api_key}",
          "BYBIT_API_SECRET": "${input:bybit_api_secret}",
          "BYBIT_TRADING_ENABLED": "${input:bybit_trading_enabled}",
          "BYBIT_TESTNET": "${input:bybit_testnet}"
        }
      }
    },
    "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",
        "default": "false"
      },
      {
        "type": "promptString",
        "id": "bybit_trading_enabled",
        "description": "Enable Bybit Trading",
        "default": "false"
      }
    ]
  }
}

Important Docker Notes:

• The -e flags are required to pass environment variables to the Docker container
• The env section sets the variables in VS Code's environment, which are then passed to Docker
• The --init flag helps with proper signal handling in containers

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

Wallet & Account Management

• get_wallet_balance: Get comprehensive wallet balance information
• get_single_coin_balance: Get balance for a specific cryptocurrency
• get_account_info: Get detailed account information and settings

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

Example Tool Calls

Get Server Time

{
  "name": "get_server_time",
  "arguments": {}
}

Get Ticker Data

{
  "name": "get_tickers",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT"
  }
}

Get Kline Data

{
  "name": "get_kline",
  "arguments": {
    "symbol": "BTCUSDT",
    "interval": "1",
    "category": "linear",
    "limit": 100
  }
}

Place Order (Requires Trading Enabled)

{
  "name": "place_order",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT",
    "side": "Buy",
    "orderType": "Limit",
    "qty": "0.001",
    "price": "50000.00",
    "orderLinkId": "my-order-123"
  }
}

Get Position Info (Requires Trading Enabled)

{
  "name": "get_position_info",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT"
  }
}

Set Leverage (Requires Trading Enabled)

{
  "name": "set_leverage",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT",
    "buyLeverage": "10",
    "sellLeverage": "10"
  }
}

Set Trading Stop (Requires Trading Enabled)

{
  "name": "set_trading_stop",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT",
    "takeProfit": "55000.00",
    "stopLoss": "45000.00",
    "positionIdx": 0
  }
}

Get Wallet Balance

{
  "name": "get_wallet_balance",
  "arguments": {
    "accountType": "UNIFIED",
    "coin": "USDT"
  }
}

Get Single Coin Balance

{
  "name": "get_single_coin_balance",
  "arguments": {
    "accountType": "UNIFIED",
    "coin": "BTC"
  }
}

Get Account Info

{
  "name": "get_account_info",
  "arguments": {}
}

Resources

• bybit://market/info: General information about available endpoints and capabilities

Troubleshooting

Common Issues

Environment Variables Not Working in Docker

• Problem: API keys not being passed to Docker container
• Solution: Use the -e flag format shown in the Docker configuration above
• Note: The env section in VS Code MCP settings sets variables in VS Code's environment, which are then passed to Docker via -e flags

Pydantic Validation Errors

• Problem: Data type mismatches (e.g., integers vs strings)
• Solution: The server includes automatic type conversion for common API inconsistencies
• Example: seq field in trade history is automatically converted from int to string

Trading Operations Disabled

• Problem: Trading tools not appearing or returning disabled errors
• Solution: Set BYBIT_TRADING_ENABLED=true in your environment variables
• Safety: This is intentional - trading is disabled by default for safety

API Permission Errors

• Problem: 401 Unauthorized or insufficient permissions
• Solution: Verify your Bybit API key has the required permissions:
  • Read-only: For market data (always safe)
  • Trade: Required for order operations
  • Position: Required for position management

Debug Mode

Enable debug logging by setting the log level:

# Local development
PYTHONPATH=src python -c "import logging; logging.basicConfig(level=logging.DEBUG)" -m bybit_mcp.main