freqtrade-mcp

I designed and built this project for my own use. All architectural decisions, tool design, and the security model are my own work. I used Claude Opus as a coding assistant during the development process. This is a research and personal-use project.

A read-only MCP (Model Context Protocol) server that provides LLM tools with introspection data about the Freqtrade codebase. Helps LLMs write faster, more reliable Freqtrade strategy code by giving them access to overridable functions, classes, variables, docstrings, type hints, and method signatures from the live Freqtrade installation.

Disclaimer

This is a research and personal-use project. It provides read-only introspection of the Freqtrade codebase to assist LLM-based code generation. It does NOT execute trades, access exchange APIs, or manage funds. It is NOT financial advice software.

The author(s) accept NO responsibility or liability for any direct, indirect, incidental, or consequential damages arising from the use of this software, including but not limited to financial losses from trading strategies developed with its assistance. Use entirely at your own risk. Always backtest thoroughly before deploying any strategy with real capital.

Features

• Strategy Method Introspection: List and inspect all overridable IStrategy methods with full signatures, type hints, and docstrings
• Class Inspection: Explore any freqtrade class — MRO, attributes, public methods
• Enum Discovery: List and inspect all trading-related enums and their values
• Codebase Search: Search for classes, functions, constants, and enums by name pattern
• Callback Details: Get detailed info about strategy callbacks (bot_start, custom_stoploss, etc.)
• Config Schema: Browse known configuration keys and their descriptions
• DataFrame Columns: Discover available DataFrame columns in strategy methods
• Documentation Access: Browse, search, and read freqtrade markdown documentation
• Version Info: Check installed freqtrade and MCP server versions

Security

• Read-only: No trading, no exchange connections, no side effects
• Input validation: All LLM inputs validated with regex whitelists
• No eval/exec: Only uses Python's inspect and ast modules
• Namespace restricted: Only inspects freqtrade.* modules
• stdio transport: Local-only, no network exposure

Requirements

• Python >= 3.13
• freqtrade >= 2026.2
• mcp[cli] >= 1.26.0

Installation

pip install freqtrade-mcp-server

Or install from source:

git clone https://github.com/yalcin/freqtrade-mcp.git
cd freqtrade-mcp
pip install -e ".[dev]"

Usage

Claude Code (CLI)

claude mcp add freqtrade-mcp \
  -e FREQTRADE_DOCS_PATH=/path/to/freqtrade/docs \
  -- "$(command -v freqtrade-mcp)"

Claude Desktop (macOS / Windows only)

Note: Claude Desktop is not available on Linux. This configuration is based on official documentation but has not been tested by the author. If you encounter issues or have corrections, pull requests are welcome.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "freqtrade": {
      "command": "freqtrade-mcp",
      "args": [],
      "env": {
        "FREQTRADE_MCP_LOG_LEVEL": "INFO",
        "FREQTRADE_DOCS_PATH": "/path/to/freqtrade/docs"
      }
    }
  }
}

OpenAI Codex CLI

Codex CLI is a terminal-based tool that runs on all platforms including Linux.

Add to your ~/.codex/config.toml (or project-scoped .codex/config.toml):

[mcp_servers.freqtrade]
command = "freqtrade-mcp"
args = []

[mcp_servers.freqtrade.env]
FREQTRADE_MCP_LOG_LEVEL = "INFO"
FREQTRADE_DOCS_PATH = "/path/to/freqtrade/docs"

Or via CLI:

codex mcp add freqtrade-mcp \
  --env FREQTRADE_DOCS_PATH="<FREQTRADE_DOCS_PATH>" \
  -- "$(command -v freqtrade-mcp)"

Codex Desktop App (macOS only)

Note: The Codex desktop app is currently macOS-only (Apple Silicon). Windows and Linux versions are not yet available. This configuration is based on official documentation but has not been tested by the author. If you encounter issues or have corrections, pull requests are welcome.

The Codex desktop app shares the same ~/.codex/config.toml configuration file with the CLI. Use the config shown in the Codex CLI section above — it applies to both.

Codex IDE Extension (VS Code / Cursor / Windsurf)

Note: Available on macOS and Linux. Windows support is experimental (WSL recommended).

The Codex IDE extension also shares ~/.codex/config.toml with the CLI and desktop app. Use the same configuration shown in the Codex CLI section. In the extension, you can access MCP settings via the gear menu.

Integrations note: Claude Code (CLI) and Codex CLI configurations have been tested and verified. Claude Desktop, Codex desktop app, and Codex IDE extension configurations are based on official documentation but have not been tested by the author. If you encounter issues or have corrections, pull requests are welcome.

Generic stdio

FREQTRADE_DOCS_PATH=/path/to/freqtrade/docs freqtrade-mcp

Available Tools

Configuration

Environment Variables

Documentation Tools

To enable documentation tools, set FREQTRADE_DOCS_PATH to the docs/ directory of a cloned freqtrade repository:

export FREQTRADE_DOCS_PATH=/path/to/freqtrade/docs

If not set, the server starts normally but documentation tools will return a guidance message instead of content. The documentation is cached with a 1-hour TTL and refreshes automatically.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

# Type check
mypy src/

License

GPLv3