@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.