Remote Setup

Deploy bybit-mcp-server as a remote MCP server with OAuth 2.0 authentication, for use with Claude Custom Connectors and other remote MCP clients.

Overview

Claude (Custom Connector)
  │
  ├─ OAuth 2.0 ──► /authorize → /login (admin password) → token
  │
  ├─ MCP Tools ──► Bearer token → Bybit API (credentials from SQLite)
  │
  └─ Settings ───► /login → /settings (enter Bybit API keys)

In remote mode, the server provides:

• OAuth 2.0 Authorization Server — Claude authenticates via standard OAuth flow
• Web Settings Page — Enter your Bybit API key/secret through a browser UI
• Encrypted Storage — API keys stored in SQLite, encrypted at rest with Fernet

Docker Compose

services:
  bybit-mcp:
    image: ghcr.io/workspace/bybit-mcp-server:latest
    ports:
      - "${BYBIT_MCP_PORT:-8000}:${BYBIT_MCP_PORT:-8000}"
    environment:
      - BYBIT_MCP_TRANSPORT=${BYBIT_MCP_TRANSPORT:-streamable-http}
      - BYBIT_MCP_HOST=${BYBIT_MCP_HOST:-0.0.0.0}
      - BYBIT_MCP_PORT=${BYBIT_MCP_PORT:-8000}
      - BYBIT_MCP_ADMIN_USERNAME=${BYBIT_MCP_ADMIN_USERNAME:-admin}
      - BYBIT_MCP_ADMIN_PASSWORD=${BYBIT_MCP_ADMIN_PASSWORD:?Set BYBIT_MCP_ADMIN_PASSWORD}
      - BYBIT_MCP_SECRET_KEY=${BYBIT_MCP_SECRET_KEY:?Set BYBIT_MCP_SECRET_KEY}
      - BYBIT_MCP_ISSUER_URL=${BYBIT_MCP_ISSUER_URL:?Set BYBIT_MCP_ISSUER_URL}
      - BYBIT_MCP_DB_PATH=/app/data/bybit_mcp.db
      - BYBIT_TESTNET=${BYBIT_TESTNET:-true}
    volumes:
      - bybit-data:/app/data
    restart: unless-stopped

volumes:
  bybit-data:

Run:

BYBIT_MCP_ADMIN_PASSWORD=your-password \
BYBIT_MCP_SECRET_KEY=your-fernet-key \
BYBIT_MCP_ISSUER_URL=https://your-server.example.com \
docker compose up -d

Or with Docker directly:

docker run -d \
  --name bybit-mcp \
  -p 8000:8000 \
  -e BYBIT_MCP_ADMIN_PASSWORD=your-secure-password \
  -e BYBIT_MCP_SECRET_KEY=your-fernet-key \
  -e BYBIT_MCP_ISSUER_URL=https://your-server.example.com \
  -v bybit-data:/app/data \
  ghcr.io/workspace/bybit-mcp-server:latest

Environment Variables

Variable	Default	Description
BYBIT_MCP_TRANSPORT	stdio	streamable-http for remote mode (set in Docker image)
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 of the server, must include scheme (e.g. https://bybit.example.com) (required)
BYBIT_MCP_DB_PATH	./bybit_mcp.db	SQLite database file path
BYBIT_TESTNET	true	Default Bybit network (can be changed in settings page)

Generating a Secret Key

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

This key encrypts Bybit API credentials at rest. Keep it safe — if lost, stored credentials cannot be decrypted.

Connect Claude Custom Connectors

1. Configure Bybit API Keys

1. Open https://your-server.example.com/login in your browser
2. Log in with your admin credentials (BYBIT_MCP_ADMIN_USERNAME / BYBIT_MCP_ADMIN_PASSWORD)
3. You'll be redirected to the /settings page
4. Enter your Bybit API key, API secret, and configure testnet/mode/recv_window
5. Click Save

2. Add Custom Connector in Claude

1. Go to Claude settings → Features → Custom Connectors
2. Add a new connector with your server URL: https://your-server.example.com
3. Claude will initiate the OAuth flow and prompt you to log in
4. After authentication, all 27 Bybit MCP tools are available

OAuth 2.0

The server implements the OAuth 2.0 Authorization Code flow with PKCE, as required by the MCP specification:

1. Client Registration — Claude auto-registers via Dynamic Client Registration (RFC 7591)
2. Authorization — Claude redirects user to /login, user enters admin credentials
3. Token Exchange — Auth code exchanged for access + refresh tokens
4. API Access — MCP tool calls authenticated via Bearer token
5. Token Refresh — Tokens automatically refreshed when expired

OAuth metadata endpoint: /.well-known/oauth-authorization-server

Reverse Proxy

For production, place the server behind a reverse proxy with TLS (nginx, Caddy, Traefik):

server {
    listen 443 ssl;
    server_name your-server.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Set BYBIT_MCP_ISSUER_URL to match your public HTTPS URL.

Security

• API keys encrypted at rest with Fernet symmetric encryption
• Admin password comparison uses constant-time comparison (timing-attack safe)
• Session cookies signed with itsdangerous (24h expiry)
• Access tokens expire after 1 hour; refresh tokens rotate on each use
• SQLite database persisted on Docker volume (/app/data)