bybit-mcp-server

A Model Context Protocol server for the Bybit V5 API.

Connect AI assistants (Claude, Cursor, etc.) to Bybit for market data, trading, and account management — locally via stdio or remotely via HTTP with OAuth authentication.

Quick Start

Local (stdio)

uvx bybit-mcp-server

Remote (Docker)

docker pull ghcr.io/workspace/bybit-mcp-server:latest
docker run -p 8000:8000 \
  -e BYBIT_MCP_ADMIN_PASSWORD=your-password \
  -e BYBIT_MCP_SECRET_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") \
  -e BYBIT_MCP_ISSUER_URL=https://your-server.example.com \
  -v bybit-data:/app/data \
  ghcr.io/workspace/bybit-mcp-server:latest

Transport Modes

Mode	Transport	Auth	Credentials	Use Case
Local	stdio	None	Env vars	Claude Desktop, Cursor
Remote	streamable-http	OAuth 2.0	Web settings page	Claude Custom Connectors, shared servers

MCP Client Configuration

Claude Desktop (Local)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bybit": {
      "command": "uvx",
      "args": ["bybit-mcp-server"],
      "env": {
        "BYBIT_API_KEY": "your-api-key",
        "BYBIT_API_SECRET": "your-api-secret",
        "BYBIT_TESTNET": "true"
      }
    }
  }
}

Claude Custom Connectors (Remote)

1. Deploy the server with Docker (see Deployment)
2. In Claude settings, add a Custom Connector:
   • URL: https://your-server.example.com
3. Claude handles OAuth automatically — you'll be prompted to log in with admin credentials
4. After connecting, visit https://your-server.example.com/settings to enter your Bybit API keys

Cursor (Local)

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "bybit": {
      "command": "uvx",
      "args": ["bybit-mcp-server"],
      "env": {
        "BYBIT_API_KEY": "your-api-key",
        "BYBIT_API_SECRET": "your-api-secret",
        "BYBIT_TESTNET": "true"
      }
    }
  }
}

Available Tools (27)

Category	Tools	Permission
Market	get_tickers, get_kline, get_orderbook, get_instruments_info, get_server_time, get_funding_rate_history, get_public_trades, get_open_interest	read
Account	get_wallet_balance, get_fee_rate, get_account_info	read
Trade	place_order, amend_order, cancel_order, cancel_all_orders, get_open_orders, get_order_history, get_trade_history	trade
Position	get_positions, set_leverage, set_trading_stop, set_auto_add_margin, get_closed_pnl	read / trade
Asset	get_coin_balance, get_coin_info, get_transfer_history, internal_transfer	read / full

Deployment

Docker Compose

services:
  bybit-mcp:
    image: ghcr.io/workspace/bybit-mcp-server:latest
    ports:
      - "8000:8000"
    environment:
      - BYBIT_MCP_ADMIN_PASSWORD=your-secure-password
      - BYBIT_MCP_SECRET_KEY=your-fernet-key
      - BYBIT_MCP_ISSUER_URL=https://your-server.example.com
    volumes:
      - bybit-data:/app/data
    restart: unless-stopped

volumes:
  bybit-data:

Generate a Fernet key:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Environment Variables

Local Mode (stdio)

Variable	Default	Description
BYBIT_API_KEY	—	API key from Bybit
BYBIT_API_SECRET	—	API secret from Bybit
BYBIT_TESTNET	true	Use testnet (true) or mainnet (false)
BYBIT_MODE	read	Permission mode: read, trade, or full
BYBIT_RECV_WINDOW	—	Request receive window in ms

Remote Mode (streamable-http)

Variable	Default	Description
BYBIT_MCP_TRANSPORT	stdio	Set to streamable-http for remote mode
BYBIT_MCP_HOST	0.0.0.0	HTTP bind address
BYBIT_MCP_PORT	8000	HTTP port
BYBIT_MCP_ADMIN_USERNAME	admin	Admin login username
BYBIT_MCP_ADMIN_PASSWORD	—	Admin login password (required)
BYBIT_MCP_SECRET_KEY	—	Fernet key for encrypting API keys at rest (required)
BYBIT_MCP_ISSUER_URL	—	Public URL with scheme, e.g. https://bybit.example.com (required)
BYBIT_MCP_DB_PATH	./bybit_mcp.db	SQLite database file path

Development

git clone https://github.com/workspace/bybit-mcp-server.git
cd bybit-mcp-server
uv sync --all-extras
uv run pytest
uv run bybit-mcp-server

Documentation

Full docs at workspace.github.io/bybit-mcp-server

License

MIT