Freqtrade MCP Server 🤖📈

A Model Context Protocol (MCP) server for cryptocurrency trading via Freqtrade — manage trades, check balances, configure strategies, backtest, and control the bot lifecycle from any MCP-compatible AI agent.

Built for AI agents. Works with Hermes Agent, Claude Code, Cursor, Windsurf, and any MCP-compatible client.

✨ Features (43 Tools)

🔧 System & Health (5 Tools)

Tool	Description
ping	Check if the freqtrade API server is reachable
get_version	Get the running bot version string
get_health	Detailed bot health (uptime, loop time, process status)
get_logs	Fetch recent bot log messages (configurable limit)
get_sysinfo	System resource usage (CPU, RAM, uptime)

🎮 Bot Lifecycle (3 Tools)

Tool	Description
start_bot	Start the trading bot (if currently stopped)
stop_bot	Stop the trading bot gracefully
stop_buying	Temporarily prevent new trades (reload config to re-enable)

📊 Trade Information (6 Tools)

Tool	Description
get_open_trades	List all open trades with current profit/loss
get_trade_detail	Full details of a specific trade by ID
get_trade_history	Historical closed trades with pagination
get_count	Open trade count vs maximum allowed
delete_trade	Permanently delete a trade from the database
cancel_open_order	Cancel an open order for a specific trade

💰 Account & Performance (10 Tools)

Tool	Description
get_balance	Full account balance across all currencies
get_profit	Profit/loss summary (total, factor, percentage)
get_daily_profit	Daily P&L breakdown for last N days
get_weekly_profit	Weekly P&L breakdown for last N weeks
get_monthly_profit	Monthly P&L breakdown for last N months
get_performance	Per-pair trade performance (best/worst)
get_stats	Stats report (exit reasons, durations)
get_entries_analysis	Analyze trade entries by buy tag
get_exits_analysis	Analyze trade exits by exit reason
get_mix_tags	Combined entry tag + exit reason analysis

🎯 Trading Actions (2 Tools)

Tool	Description
force_entry	Force-enter a trade (long/short, with leverage & tags)
force_exit	Force-exit (sell) an open trade (partial exit supported)

📋 Pairs & Whitelist/Blacklist (4 Tools)

Tool	Description
get_whitelist	Active trading pair whitelist
get_blacklist	Currently blacklisted pairs
add_to_blacklist	Add one or more pairs to blacklist
get_pairlists_available	List available pairlist handler plugins
get_available_pairs	Pairs available for backtesting (filterable)

🔒 Pair Locks (3 Tools)

Tool	Description
get_locks	All active pair locks
lock_pair	Lock a pair (with expiration, side, reason)
unlock_pair	Remove a pair lock by ID

🧠 Strategies & Market Data (4 Tools)

Tool	Description
list_strategies	Available strategy classes
get_strategy_detail	Strategy information (code, params, timeframe)
get_plot_config	Plot configuration from active strategy
get_pair_candles	Live OHLCV candle data (any pair/timeframe)
get_pair_history	Historic analyzed dataframe for a pair + strategy

⚙️ Configuration (2 Tools)

Tool	Description
get_config	Current (sanitized) bot configuration
reload_config	Reload config from disk (no restart needed)

🗃️ Custom Data (2 Tools)

Tool	Description
get_custom_data	Custom data stored for a specific trade
get_open_trades_custom_data	Custom data across all open trades

🚀 Quick Start

1. Install

pip install git+https://github.com/ceeyang-ai/freqtrade-mcp-server.git

2. Start Freqtrade (dry-run for testing)

Create a minimal config (config.json):

{
    "max_open_trades": 3,
    "stake_currency": "USDT",
    "stake_amount": 50,
    "dry_run": true,
    "dry_run_wallet": 1000,
    "timeframe": "5m",
    "exchange": {
        "name": "binance",
        "pair_whitelist": ["BTC/USDT", "ETH/USDT"]
    },
    "api_server": {
        "enabled": true,
        "listen_port": 8080,
        "username": "freqtrader",
        "password": "your_password",
        "jwt_secret_key": "a-very-long-random-string-at-least-32-chars"
    }
}

freqtrade trade --strategy SampleStrategy --config config.json

3. Run the MCP Server

export FREQTRADE_URL=http://127.0.0.1:8080
export FREQTRADE_USERNAME=freqtrader
export FREQTRADE_PASSWORD=your_password

freqtrade-mcp-server

Configuration via Environment Variables

Variable	Required	Default	Description
FREQTRADE_URL	No	http://127.0.0.1:8080	Freqtrade API server URL
FREQTRADE_USERNAME	No	freqtrade	API username from api_server config
FREQTRADE_PASSWORD	No	""	API password from api_server config

🔌 Usage with AI Agents

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  freqtrade:
    command: "freqtrade-mcp-server"
    env:
      FREQTRADE_URL: "http://127.0.0.1:8080"
      FREQTRADE_USERNAME: "freqtrader"
      FREQTRADE_PASSWORD: "your_password"

Then ask your agent: "What's my current crypto portfolio balance?", "Force-enter BTC/USDT long", "Run a backtest on BTC/USDT"

Claude Code / Cursor

{
  "mcpServers": {
    "freqtrade": {
      "command": "freqtrade-mcp-server",
      "env": {
        "FREQTRADE_URL": "http://127.0.0.1:8080",
        "FREQTRADE_USERNAME": "freqtrader",
        "FREQTRADE_PASSWORD": "your_password"
      }
    }
  }
}

🛠 Requirements

• Python 3.10+
• Freqtrade instance running with API server enabled (api_server.enabled: true)
• freqtrade-client >= 2026.5 (installed automatically)
• mcp >= 1.0 (installed automatically)

🧪 Development

git clone https://github.com/ceeyang-ai/freqtrade-mcp-server.git
cd freqtrade-mcp-server
pip install -e .

# Run integration tests (requires running Freqtrade instance)
python test_integration.py

🤝 Related Projects

• doc-mcp-server — Document processing (PDF, text conversion)
• viz-mcp-server — Data visualization (matplotlib/seaborn charts)
• webx-mcp-server — Web page extraction and conversion

📄 License

MIT — free for personal and commercial use.