# @furkankoykiran/freqtrade-mcp

[![CI](https://github.com/furkankoykiran/freqtrade-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/furkankoykiran/freqtrade-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/%40furkankoykiran%2Ffreqtrade-mcp)](https://www.npmjs.com/package/@furkankoykiran/freqtrade-mcp)
[![GitHub Package](https://img.shields.io/badge/GitHub%20Packages-available-blue?logo=github)](https://github.com/furkankoykiran/freqtrade-mcp/pkgs/npm/freqtrade-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/node/v/%40furkankoykiran%2Ffreqtrade-mcp)](package.json)

TypeScript MCP server for Freqtrade — connect AI agents (Claude, Cursor, Cline) to your crypto trading bot via its REST API.

Built with the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk), it exposes **15 tools** covering account stats, trade management, market data, pair list control, trade execution, and bot lifecycle — all accessible from any MCP-compatible client.

---

## Features

| Category | Tools |
|---|---|
| **Account** | `get_profit_stats`, `get_balance`, `get_performance` |
| **Trades** | `get_open_trades`, `get_trade`, `get_trade_history` |
| **Market Data** | `get_market_data` |
| **Pair Lists** | `get_whitelist`, `get_blacklist`, `add_to_blacklist`, `remove_from_blacklist` |
| **Execution** | `execute_trade`, `force_exit_trade` |
| **Lifecycle** | `start_bot`, `stop_bot`, `reload_config`, `get_bot_info`, `get_locks`, `delete_lock` |

---

## Prerequisites

1. **Freqtrade** running with the REST API enabled (see [Freqtrade REST API docs](https://www.freqtrade.io/en/stable/rest-api/))
2. **Node.js 18+** (`node --version`)

### Enable the Freqtrade REST API

Add the following to your Freqtrade `config.json`:

```json
"api_server": {
  "enabled": true,
  "listen_ip_address": "127.0.0.1",
  "listen_port": 8080,
  "verbosity": "error",
  "enable_openapi": false,
  "jwt_secret_key": "change-this-to-a-random-32-char-string",
  "username": "Freqtrader",
  "password": "YourStrongPassword"
}
```

---

## Installation

### Option 1 — Run directly with npx (no install required)

```bash
FREQTRADE_PASSWORD=yourpassword npx @furkankoykiran/freqtrade-mcp
```

### Option 2 — Install globally from npm

```bash
npm install -g @furkankoykiran/freqtrade-mcp
FREQTRADE_PASSWORD=yourpassword freqtrade-mcp
```

### Option 3 — Install from GitHub Packages

```bash
npm install -g @furkankoykiran/freqtrade-mcp --registry=https://npm.pkg.github.com
FREQTRADE_PASSWORD=yourpassword freqtrade-mcp
```

### Option 4 — Build from source

```bash
git clone https://github.com/furkankoykiran/freqtrade-mcp.git
cd freqtrade-mcp
npm install
npm run build
node build/index.js
```

---

## Configuration

The server is configured entirely via environment variables — no config file needed.

| Variable | Default | Description |
|---|---|---|
| `FREQTRADE_API_URL` | `http://127.0.0.1:8080` | Base URL of the Freqtrade API server |
| `FREQTRADE_USERNAME` | `Freqtrader` | API username from your Freqtrade config |
| `FREQTRADE_PASSWORD` | *(empty)* | API password — **required** |

Copy `.env.example` to `.env` and fill in your values for local development.

---

## MCP Client Setup

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "freqtrade": {
      "command": "npx",
      "args": ["-y", "@furkankoykiran/freqtrade-mcp"],
      "env": {
        "FREQTRADE_API_URL": "http://127.0.0.1:8080",
        "FREQTRADE_USERNAME": "Freqtrader",
        "FREQTRADE_PASSWORD": "YourStrongPassword"
      }
    }
  }
}
```

### VS Code (Cline / Continue)

Add to your MCP server settings:

```json
{
  "freqtrade": {
    "command": "npx",
    "args": ["-y", "@furkankoykiran/freqtrade-mcp"],
    "env": {
      "FREQTRADE_API_URL": "http://127.0.0.1:8080",
      "FREQTRADE_USERNAME": "Freqtrader",
      "FREQTRADE_PASSWORD": "YourStrongPassword"
    }
  }
}
```

### Built from source

```json
{
  "freqtrade": {
    "command": "node",
    "args": ["/absolute/path/to/freqtrade-mcp/build/index.js"],
    "env": {
      "FREQTRADE_API_URL": "http://127.0.0.1:8080",
      "FREQTRADE_USERNAME": "Freqtrader",
      "FREQTRADE_PASSWORD": "YourStrongPassword"
    }
  }
}
```

---

## Available Tools

### Account

#### `get_profit_stats`
Retrieve current profit/loss statistics: total profit, win/loss ratio, best pair, drawdown, trading volume, and more.

#### `get_balance`
Retrieve the current account balance across all currencies, including free, used, and total amounts.

#### `get_performance`
Retrieve per-pair trading performance metrics, including profit and trade count.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pair` | string | No | Filter to a specific pair (e.g. `BTC/USDT`) |

---

### Trades

#### `get_open_trades`
Retrieve all currently active trades, including entry price, current profit, stake amount, and duration.

#### `get_trade`
Retrieve detailed information about a specific trade by its ID.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `trade_id` | number | Yes | Numeric trade ID |

#### `get_trade_history`
Retrieve closed trade history with optional pagination.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `limit` | number | No | Max trades to return (max 500) |
| `offset` | number | No | Pagination offset |

---

### Market Data

#### `get_market_data`
Retrieve live OHLCV candlestick data for a trading pair.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pair` | string | Yes | Trading pair (e.g. `BTC/USDT`) |
| `timeframe` | enum | Yes | `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, etc. |
| `limit` | number | No | Number of candles (max 500) |

---

### Pair Lists

#### `get_whitelist` / `get_blacklist`
Retrieve the current whitelist / blacklist.

#### `add_to_blacklist`
Add a trading pair to the blacklist.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pair` | string | Yes | Pair to blacklist (e.g. `ETH/USDT`) |

#### `remove_from_blacklist`
Remove a trading pair from the blacklist.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pair` | string | Yes | Pair to remove |

---

### Trade Execution

#### `execute_trade`
Force-enter a trade, bypassing strategy signals. The bot manages the position after entry.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pair` | string | Yes | Trading pair (e.g. `BTC/USDT`) |
| `side` | `long`/`short` | Yes | Trade direction |
| `stake_amount` | number | No | Amount in stake currency |
| `price` | number | No | Limit price (omit for market order) |
| `order_type` | `limit`/`market` | No | Order type |

**Natural language examples:**
- *"buy 100 USDT of BTC"* → `pair=BTC/USDT`, `side=long`, `stake_amount=100`
- *"short ETH/USDT at 2000"* → `pair=ETH/USDT`, `side=short`, `price=2000`

#### `force_exit_trade`
Force-exit an open trade. Supports full and partial exits.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `trade_id` | number | Yes | Trade ID to exit |
| `order_type` | `limit`/`market` | No | Exit order type (default: market) |
| `amount` | number | No | Partial exit amount |

---

### Bot Lifecycle

#### `start_bot` / `stop_bot`
Start or stop the trading bot.

#### `reload_config`
Reload the bot configuration from disk without restarting the process.

#### `get_bot_info`
Retrieve bot version and the timestamp of the last strategy run cycle.

#### `get_locks`
Retrieve all active trade locks.

#### `delete_lock`
Remove a specific trade lock by ID.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `lock_id` | number | Yes | Lock ID to remove |

---

## Development

```bash
# Clone and install
git clone https://github.com/furkankoykiran/freqtrade-mcp.git
cd freqtrade-mcp
npm install

# Run in development mode (auto-reloads on change)
cp .env.example .env
# Edit .env with your Freqtrade credentials
npm run dev

# Type-check
npm run typecheck

# Lint
npm run lint

# Build for production
npm run build
```

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

Set the environment variables in the Inspector UI and verify all 15 tools are listed.

---

## Contributing

Contributions are welcome. Please read the [contributing guidelines](.github/PULL_REQUEST_TEMPLATE.md) and open an issue before submitting a pull request for significant changes.

---

## License

MIT — see [LICENSE](LICENSE).