MCP Directory

How to add Freqtrade-MCP to Windsurf

Control a Freqtrade crypto trading bot through its REST API from any MCP-compatible AI agent. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 121★ · stdio · no auth

Windsurf config for Freqtrade-MCP

pip install freqtrade-client mcp[cli]
{
  "mcpServers": {
    "freqtrade-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/your/path/to/freqtrade-mcp",
        "run",
        "__main__.py"
      ],
      "env": {
        "FREQTRADE_API_URL": "http://127.0.0.1:8080",
        "FREQTRADE_USERNAME": "your_username",
        "FREQTRADE_PASSWORD": "your_password"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Freqtrade-MCP config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Freqtrade-MCP's tools become available to Cascade.

Before you start

  • Python 3.13+
  • A running Freqtrade instance with the REST API enabled (api_server.enabled = true)
  • Git (for cloning the repository)
  • Freqtrade API URL, username, and password

What Freqtrade-MCP can do in Windsurf

fetch_market_data

Fetch OHLCV data for a pair. Parameters: pair (str), timeframe (str).

fetch_bot_status

Get open trade status. No parameters.

fetch_profit

Get profit summary. No parameters.

fetch_balance

Get account balance. No parameters.

fetch_performance

Get performance metrics. No parameters.

fetch_whitelist

Get whitelist of pairs. No parameters.

fetch_blacklist

Get blacklist of pairs. No parameters.

fetch_trades

Get trade history. No parameters.

Security

The server connects to a running Freqtrade instance using FREQTRADE_API_URL, FREQTRADE_USERNAME, and FREQTRADE_PASSWORD environment variables. These credentials control a live trading bot — the exposed tools can place trades and start/stop the bot, so the server should only be granted to trusted agents. The README's sample Freqtrade config binds the REST API to 127.0.0.1; do not expose it publicly.

Freqtrade-MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Freqtrade-MCP config there under the "mcpServers" key and restart the client.

Is Freqtrade-MCP safe to use with Windsurf?

The server connects to a running Freqtrade instance using FREQTRADE_API_URL, FREQTRADE_USERNAME, and FREQTRADE_PASSWORD environment variables. These credentials control a live trading bot — the exposed tools can place trades and start/stop the bot, so the server should only be granted to trusted agents. The README's sample Freqtrade config binds the REST API to 127.0.0.1; do not expose it publicly.

What do I need running before using this server?

A Freqtrade instance with its REST API enabled. Add an api_server section to your Freqtrade config and set api_server.enabled to true (the README shows a sample with listen_port 8080 bound to 127.0.0.1).

How does the server authenticate to Freqtrade?

Through the FREQTRADE_API_URL, FREQTRADE_USERNAME, and FREQTRADE_PASSWORD environment variables set in the MCP client config, which correspond to your Freqtrade REST API URL and credentials.

How is the server launched?

Via uv over stdio: `uv --directory /your/path/to/freqtrade-mcp run __main__.py`, after cloning the repo and installing the freqtrade-client and mcp[cli] dependencies.

View repo Full Freqtrade-MCP page