# bybit-mcp-server

A [Model Context Protocol](https://modelcontextprotocol.io/) server for the [Bybit](https://bybit.com) 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)

```bash
uvx bybit-mcp-server
```

### Remote (Docker)

```bash
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`:

```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](#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`:

```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

```yaml
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:

```bash
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

```bash
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](https://workspace.github.io/bybit-mcp-server)

## License

MIT