# CCXT MCP Server

[![npm version](https://img.shields.io/npm/v/@lazydino/ccxt-mcp.svg)](https://www.npmjs.com/package/@lazydino/ccxt-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@lazydino/ccxt-mcp.svg)](https://www.npmjs.com/package/@lazydino/ccxt-mcp)
[![GitHub stars](https://img.shields.io/github/stars/lazy-dinosaur/ccxt-mcp.svg)](https://github.com/lazy-dinosaur/ccxt-mcp/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[한국어 버전(Korean version)](README.ko.md)

CCXT MCP Server is a server that allows AI models to interact with cryptocurrency exchange APIs through the [Model Context Protocol (MCP)](https://github.com/anthropics/anthropic-cookbook/tree/main/model-context-protocol). This server uses the [CCXT library](https://github.com/ccxt/ccxt) to provide access to more than 100 cryptocurrency exchanges and their trading capabilities.

## 🚀 Quick Start

```bash
# Install the package globally
npm install -g @lazydino/ccxt-mcp

# Run with default settings
ccxt-mcp

# or run without installation
npx @lazydino/ccxt-mcp
```

## Installation and Usage

### Global Installation

```bash
# Install the package globally
npm install -g @lazydino/ccxt-mcp
```

### Running with npx

You can run it directly without installation:

```bash
# Using default settings
npx @lazydino/ccxt-mcp

# Using custom configuration file
npx @lazydino/ccxt-mcp --config /path/to/config.json
```

View help:

```bash
npx @lazydino/ccxt-mcp --help
```

## Configuration

### Registering the MCP Server in Claude Desktop

1. **Open Claude Desktop Settings**:

   - Go to the Settings menu in the Claude Desktop app
   - Find the "MCP Servers" section

2. **Add a New MCP Server**:

   - Click the "Add Server" button
   - Server name: `ccxt-mcp`
   - Command: `npx @lazydino/ccxt-mcp`
   - Additional arguments (optional): `--config /path/to/config.json`

3. **Save and Test the Server**:
   - Save the settings
   - Test the connection with the "Test Connection" button

### Configuration Methods - Two Options

#### Option 1: Include Account Information Directly in Claude Desktop Settings (Basic Method)

This method includes CCXT account information directly in the Claude Desktop settings file (claude_desktop_config.json):

```json
{
  "mcpServers": {
    "ccxt-mcp": {
      "command": "npx",
      "args": ["-y", "@lazydino/ccxt-mcp"],
      "mcpBearerToken": "YOUR_MCP_TOKEN",
      "accounts": [
        {
          "name": "bybit_main",
          "exchangeId": "bybit",
          "apiKey": "YOUR_API_KEY",
          "secret": "YOUR_SECRET_KEY",
          "defaultType": "spot"
        },
        {
          "name": "bybit_futures",
          "exchangeId": "bybit",
          "apiKey": "YOUR_API_KEY",
          "secret": "YOUR_SECRET_KEY",
          "defaultType": "swap"
        }
      ]
    }
  }
}
```

Using this method, you don't need a separate configuration file. All settings are integrated into the Claude Desktop configuration file.

#### Option 2: Using a Separate Configuration File (Advanced Method)

To separate account information into a separate configuration file, set up as follows:

1. **Create a Separate Configuration File** (e.g., `ccxt-config.json`):

```json
{
  "mcpBearerToken": "YOUR_MCP_TOKEN",
  "accounts": [
    {
      "name": "bybit_main",
      "exchangeId": "bybit",
      "apiKey": "YOUR_API_KEY",
      "secret": "YOUR_SECRET_KEY",
      "defaultType": "spot"
    },
    {
      "name": "bybit_futures",
      "exchangeId": "bybit",
      "apiKey": "YOUR_API_KEY",
      "secret": "YOUR_SECRET_KEY",
      "defaultType": "swap"
    }
  ]
}
```

> **Important**: The configuration file must contain an `accounts` array at the root level, as shown above.

> **Important**: If you run the server in HTTP+SSE mode (`--sse`), set `mcpBearerToken` in the same config file. Clients must send `Authorization: Bearer <mcpBearerToken>` on requests.

2. **Specify the Configuration File Path in Claude Desktop Settings**:

```json
{
  "mcpServers": {
    "ccxt-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@lazydino/ccxt-mcp",
        "--config",
        "/path/to/ccxt-config.json"
      ]
    }
  }
}
```

> **Note**: When using a separate configuration file with the `--config` option, the server will look for the `accounts` array directly in the root of the JSON file, not in `mcpServers.ccxt-mcp.accounts` path.

3. **Running with External Configuration File from Command Line**:

```bash
# Using custom configuration file
npx @lazydino/ccxt-mcp --config /path/to/ccxt-config.json
```

You can find an example configuration file at `config/ccxt-config.example.json` in the repository.

> **Reasons to Use a Separate Configuration File**:
>
> - Prevents recursive reference issues
> - Separates sensitive information like API keys
> - Easier multi-environment configuration (development, testing, production)
> - Improved configuration file version control

## Key Features

- **Market Information Retrieval**:

  - List exchanges
  - View market information by exchange
  - Get price information for specific symbols
  - View order book information for specific symbols
  - Search historical OHLCV data

- **Trading Functions**:

  - Create market/limit orders
  - Cancel orders and check status
  - View account balances
  - Check trading history

- **Trading Analysis**:

  - Daily/weekly/monthly performance analysis
  - Win rate calculation (last 7 days, 30 days, all time)
  - Average profit/loss ratio (R-multiple)
  - Maximum consecutive loss/profit series analysis
  - Asset variation tracking
  - Comprehensive performance metrics
  - Trade pattern recognition
  - Period-based return calculations

- **Position Management**:

  - Capital ratio trading (e.g., enter with 5% of account capital)
  - Futures market leverage setting (1-100x)
  - Dynamic position sizing (volatility-based)
  - Split buy/sell strategy implementation

- **Risk Management**:
  - Technical indicator-based stop loss setting (e.g., lowest point among 10 candles on 5-minute chart)
  - Volatility-based stop loss/take profit (ATR multiples)
  - Maximum allowable loss limit (daily/weekly)
  - Dynamic take profit setting (trailing profit)

## How It Works

```
User <--> AI Model(Claude/GPT) <--> MCP Protocol <--> CCXT MCP Server <--> Cryptocurrency Exchange API
```

1. **User**: Requests like "Tell me the Bitcoin price" or "Buy Ethereum on my Binance account"
2. **AI Model**: Understands user requests and determines which MCP tools/resources to use
3. **MCP Protocol**: Standardized communication between AI and CCXT MCP server
4. **CCXT MCP Server**: Communicates with cryptocurrency exchange APIs using the CCXT library
5. **Exchange API**: Provides actual data and executes trade orders

## Using with AI Models

When registered with Claude Desktop, you can make the following types of requests to AI models:

### Cautions and Recommended Prompts

When using AI models, consider the following cautions and use the prompt below for effective trading:

```
Your goal is to execute trades using the ccxt tools as much as possible
Cautions:
- Accurately identify whether it's a futures market or spot market before proceeding with trades
- If there's no instruction about percentage of capital or amount to use, always calculate and execute trades using the entire available capital
```

**Notes:**

- AI models sometimes confuse futures trading with spot trading.
- Without clear guidance on trading capital size, AI might get confused.
- Using the above prompt helps clearly communicate your trading intentions.

### Basic Query Examples

```
Check and compare the current Bitcoin price on binance and coinbase.
```

### Advanced Trading Query Examples

**Position Management**

```
Open a long position on BTC/USDT futures market in my Bybit account (bybit_futures) with 5% of capital using 10x leverage.
Enter based on moving average crossover strategy and set stop loss at the lowest point among the 12 most recent 5-minute candles.
```

**Performance Analysis**

```
Analyze my Binance account (bybit_main) trading records for the last 7 days and show me the win rate, average profit, and maximum consecutive losses.
```

**Detailed Trading Analytics**

```
Analyze my trading performance on the bybit_futures account for BTC/USDT over the last 30 days. Calculate win rate, profit factor, and identify any patterns in my winning trades.
```

```
Show me the monthly returns for my bybit_main account over the past 90 days and identify my best and worst trading months.
```

```
Analyze my consecutive wins and losses on my bybit_futures account and tell me if I have any psychological patterns affecting my trading after losses.
```

## Development

### Building from Source

```bash
# Clone repository
git clone https://github.com/lazy-dinosaur/ccxt-mcp.git

# Navigate to project directory
cd ccxt-mcp

# Install dependencies
npm install

# Build
npm run build
```

## Docker

### Build and Run with Docker Compose

1. Create a config file:

```bash
cp config/ccxt-config.example.json config/ccxt-config.json
```

Then fill in your real API keys in `config/ccxt-config.json`.
Also set `mcpBearerToken` in that same config file.
2. Build image:

```bash
docker compose build
```

3. Start the MCP server in background (SSE mode on localhost:2298):

```bash
docker compose up -d
```

4. Verify local health endpoint:

```bash
curl -H "Authorization: Bearer YOUR_MCP_TOKEN" http://127.0.0.1:2298/healthz
```

This Compose setup runs MCP over HTTP+SSE (`/sse` + `/messages`) on localhost:2298 for reverse proxying.

### Remote MCP Client Configuration

If your MCP client runs on another host, use an Nginx reverse proxy on this machine.

1. Copy `ccxt-mcp.nginx` to your Nginx config location and update certificate paths:

```bash
sudo cp ccxt-mcp.nginx /etc/nginx/conf.d/ccxt-mcp.conf
```

2. Edit `/etc/nginx/conf.d/ccxt-mcp.conf` and set:

- `ssl_certificate`
- `ssl_certificate_key`
- Authorization header forwarding (already included in this file)

3. Reload Nginx:

```bash
sudo nginx -t && sudo systemctl reload nginx
```

4. In your MCP client, configure the MCP server URL to your TLS endpoint:

- SSE URL: `https://YOUR_HOSTNAME_OR_IP:42299/sse`
- Messages URL: `https://YOUR_HOSTNAME_OR_IP:42299/messages`
- Header: `Authorization: Bearer YOUR_MCP_TOKEN`

You can generate a strong token with:

```bash
openssl rand -hex 32
```

Config example:

```json
{
  "mcpBearerToken": "YOUR_MCP_TOKEN",
  "accounts": [
    {
      "name": "bybit_main",
      "exchangeId": "bybit",
      "apiKey": "YOUR_API_KEY",
      "secret": "YOUR_SECRET_KEY"
    }
  ]
}
```

Port note:
- `42298` is HTTP (redirect only)
- `42299` is HTTPS
- `2298` comes from `CCXT` on a phone keypad

If your MCP client accepts command-based MCP servers instead of URL configuration, configure `ccxt-mcp` with:

- Command: `docker`
- Args:

```json
[
  "run",
  "--rm",
  "-i",
  "-p",
  "127.0.0.1:2298:2298",
  "-v",
  "/absolute/path/to/ccxt-mcp/config/ccxt-config.json:/config/ccxt-config.json:ro",
  "ccxt-mcp:local",
  "--sse",
  "--host",
  "0.0.0.0",
  "--port",
  "2298",
  "--config",
  "/config/ccxt-config.json"
]
```

Build the image first with `docker compose build`.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

Distributed under the MIT License. See the LICENSE file for more information.

## ❤️ Support

If you find this project useful, please consider giving it a ⭐️ on GitHub!