@furkankoykiran/freqtrade-mcp

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, 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)
2. Node.js 18+ (node --version)

Enable the Freqtrade REST API

Add the following to your Freqtrade config.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)

FREQTRADE_PASSWORD=yourpassword npx @furkankoykiran/freqtrade-mcp

Option 2 — Install globally from npm

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

Option 3 — Install from GitHub Packages

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

Option 4 — Build from source

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):

{
  "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:

{
  "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

{
  "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

# 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

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 and open an issue before submitting a pull request for significant changes.

License

MIT — see LICENSE.