# Bybit MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that provides read-only access to Bybit's cryptocurrency exchange API.

**THIS IS ALPHA QUALITY SOFTWARE - USE AT YOUR OWN RISK!**

Only ever use a read-only API key with this server. I wouldn't trust my code with your "money" and neither should you!

## Features

This MCP server provides the following tools for interacting with Bybit's API:

- `get_ticker`: Get real-time ticker information for a trading pair
- `get_orderbook`: Get orderbook (market depth) data for a trading pair
- `get_kline`: Get kline/candlestick data for a trading pair
- `get_market_info`: Get detailed market information for trading pairs
- `get_trades`: Get recent trades for a trading pair
- `get_instrument_info`: Get detailed instrument information for a specific trading pair
- `get_wallet_balance`: Get wallet balance information for the authenticated user
- `get_positions`: Get current positions information for the authenticated user
- `get_order_history`: Get order history for the authenticated user
- `get_ml_rsi`: Get machine learning-based RSI (Relative Strength Index) for a trading pair
- `get_market_structure`: Get market structure information for a trading pair
- `get_order_blocks`: Detect institutional order accumulation zones
- `get_order_history`: Get order history for the authenticated user
- `get_orderbook`: Get orderbook (market depth) data for a trading pair
- `get_ticker`: Get real-time ticker information for a trading pair

There is also a **highly experimental** WebUI, see [WebUI README](webui/README.md) for details.

![WebUI Screenshot](webui/screenshot.png)

All code is subject to breaking changes and feature additions / removals as I continue to develop this project.

## Requirements & Installation

1. Node.js (v22+)
2. pnpm (`npm i -g pnpm`)
3. If you want to run the Ollama client as shown in the quick start below, you'll need Ollama installed and running, as well as your model of choice.

```bash
pnpm i
```

## Quick Start

To install packages build everything and start the interactive client:
```bash
pnpm i
```

Copy the .env.example file to .env and fill in your details.

```bash
cp .env.example .env
code .env
```

### MCP-Server (Only)

#### Stdio Transport (Default)

```bash
pnpm serve
```

#### HTTP/SSE Transport

```bash
pnpm start:http
```

The HTTP server runs on port 8080 by default and provides both modern Streamable HTTP and legacy SSE transports, making it compatible with web applications and various MCP clients. See [HTTP Server Documentation](docs/HTTP_SERVER.md) for detailed information.

### MCP-Server and Ollama client

Install required client packages:

```bash
(cd client && pnpm i)
```

Copy the client .env.example file to .env and fill in your details.

```bash
cp client/.env.example client/.env
code client/.env
```

Then to start the client and server in one command:

```bash
pnpm start
```

## Configuration

### Environment Variables

The server requires Bybit API credentials to be set as environment variables:

- `BYBIT_API_KEY`: Your Bybit API key (required)
- `BYBIT_API_SECRET`: Your Bybit API secret  (required) - **IMPORTANT - Only ever create a read-only API key!**
- `BYBIT_USE_TESTNET`: Set to "true" to use testnet instead of mainnet (optional, defaults to false)
- `DEBUG`: Set to "true" to enable debug logging (optional, defaults to false)

Client environment variables (./client/.env):

- `OLLAMA_HOST`: The host of the Ollama server (defaults to http://localhost:11434)
- `DEFAULT_MODEL`: The default model to use for chat (defaults to qwen3-30b-a3b-ud-nothink-128k:q4_k_xl)

### MCP Settings Configuration

To use this server with MCP clients, you need to add it to your MCP settings configuration file. The file location depends on your client:

#### MCP Example - Claude Desktop

Location: `~/Library/Application\ Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "bybit": {
      "command": "node",
      "args": ["/path/to/bybit-mcp/build/index.js"],
      "env": {
        "BYBIT_API_KEY": "your-api-key",
        "BYBIT_API_SECRET": "your-api-secret",
        "BYBIT_USE_TESTNET": "false"
      }
    }
  }
}
```

#### MCP Example - [gomcp](https://github.com/sammcj/gomcp)

Location: `~/.config/gomcp/config.yaml`

```yaml
mcp_servers:
  - name: "bybit"
    command: "cd /path/to/bybit-mcp && pnpm run serve"
    arguments: []
    env:
      BYBIT_API_KEY: ""      # Add your Bybit API **READ ONLY** key here
      BYBIT_API_SECRET: ""   # Add your Bybit API **READ ONLY** secret here
      BYBIT_USE_TESTNET: "true"  # Set to false for production
      DEBUG: "false"         # Optional: Set to true for debug logging
```

## Client Integration

This package includes a TypeScript client that provides a command-line interface for interacting with both Ollama LLMs and the bybit-mcp server. The client supports:

- Interactive chat with Ollama models
- Direct access to all bybit-mcp trading tools
- Automatic server management
- Environment-based configuration
- Debug logging

For detailed client documentation, see the [client README](client/README.md).

## Running the Server

### Production

1. Build the server:
```bash
pnpm build
```

2. Run the server:
```bash
node build/index.js
```

### Development

For development with automatic TypeScript recompilation:
```bash
pnpm watch
```

To inspect the MCP server during development:
```bash
pnpm inspector
```

## Tool Documentation

### Get Ticker Information

```typescript
{
  "name": "get_ticker",
  "arguments": {
    "symbol": "BTCUSDT",
    "category": "spot" // optional, defaults to "spot"
  }
}
```

### Get Orderbook Data

```typescript
{
  "name": "get_orderbook",
  "arguments": {
    "symbol": "BTCUSDT",
    "category": "spot", // optional, defaults to "spot"
    "limit": 25 // optional, defaults to 25 (available: 1, 25, 50, 100, 200)
  }
}
```

### Get Kline/Candlestick Data

```typescript
{
  "name": "get_kline",
  "arguments": {
    "symbol": "BTCUSDT",
    "category": "spot", // optional, defaults to "spot"
    "interval": "1", // optional, defaults to "1" (available: "1", "3", "5", "15", "30", "60", "120", "240", "360", "720", "D", "M", "W")
    "limit": 200 // optional, defaults to 200 (max 1000)
  }
}
```

### Get Market Information

```typescript
{
  "name": "get_market_info",
  "arguments": {
    "category": "spot", // optional, defaults to "spot"
    "symbol": "BTCUSDT", // optional, if not provided returns info for all symbols in the category
    "limit": 200 // optional, defaults to 200 (max 1000)
  }
}
```

### Get Recent Trades

```typescript
{
  "name": "get_trades",
  "arguments": {
    "symbol": "BTCUSDT",
    "category": "spot", // optional, defaults to "spot"
    "limit": 200 // optional, defaults to 200 (max 1000)
  }
}
```

### Get Instrument Information

```typescript
{
  "name": "get_instrument_info",
  "arguments": {
    "symbol": "BTCUSDT", // required
    "category": "spot" // optional, defaults to "spot"
  }
}
```

Returns detailed information about a trading instrument including:

- Base and quote currencies
- Trading status
- Lot size filters (min/max order quantities)
- Price filters (tick size)
- Leverage settings (for futures)
- Contract details (for futures)

### Get Wallet Balance

```typescript
{
  "name": "get_wallet_balance",
  "arguments": {
    "accountType": "UNIFIED", // required (available: "UNIFIED", "CONTRACT", "SPOT")
    "coin": "BTC" // optional, if not provided returns all coins
  }
}
```

### Get Positions

```typescript
{
  "name": "get_positions",
  "arguments": {
    "category": "linear", // required (available: "linear", "inverse")
    "symbol": "BTCUSDT", // optional
    "baseCoin": "BTC", // optional
    "settleCoin": "USDT", // optional
    "limit": 200 // optional, defaults to 200
  }
}
```

### Get Order History

```typescript
{
  "name": "get_order_history",
  "arguments": {
    "category": "spot", // required (available: "spot", "linear", "inverse")
    "symbol": "BTCUSDT", // optional
    "baseCoin": "BTC", // optional
    "orderId": "1234567890", // optional
    "orderLinkId": "myCustomId", // optional
    "orderStatus": "Filled", // optional (available: "Created", "New", "Rejected", "PartiallyFilled", "PartiallyFilledCanceled", "Filled", "Cancelled", "Untriggered", "Triggered", "Deactivated")
    "orderFilter": "Order", // optional (available: "Order", "StopOrder")
    "limit": 200 // optional, defaults to 200
  }
}
```

## Supported Categories

- `spot`: Spot trading
- `linear`: Linear perpetual contracts
- `inverse`: Inverse perpetual contracts

## License

MIT