Backtrader MCP

What cloudQuant/backtrader-mcp does

cloudQuant/backtrader-mcp MCP server supports local, reproducible strategy development and backtesting with the CloudQuant Backtrader distribution. It accepts data through registered filesystem roots, treats CSV inputs as immutable datasets, and turns typed strategy intent into private drafts before a reviewed draft can be run.

The project is intended for the 💰 Finance & Fintech category, specifically workflows that need repeatable historical-data experiments without connecting to a broker. It does not provide live trading, credentials, network transports, arbitrary Python execution, or broker operations.

How it works

The server communicates through the MCP Python SDK over local stdio. Its state is kept in SQLite with WAL support, while content-addressed data, draft files, HMAC capabilities, filesystem locks, idempotency records, and startup recovery support controlled execution.

A typical workflow prepares a strategy run, reviews the generated draft and target changes, starts the run, then checks status or retrieves the result. Runs execute in bounded subprocesses using a verified CloudQuant Backtrader runtime. The runtime must resolve to the expected GitHub origin; another fork or the public PyPI package is rejected before execution.

The packaged catalog contains metadata for functional tests and strategy packages, plus separate current-fork templates. Catalog results can be paged, searched, and refreshed from explicitly registered read-only source roots. Refreshing scans and hashes metadata without importing, executing, or changing corpus files.

Setup and configuration

Install Python 3.10 or newer in a dedicated virtual environment, then install the package with the supplied constraints file. The package installs its pinned CloudQuant Backtrader dependency when applicable. The backtrader-mcp install-backtrader command can install that dependency separately when it is absent, while leaving another existing distribution untouched and reporting a warning.

Set BACKTRADER_MCP_STATE_ROOT to a private absolute state directory. Configure BACKTRADER_MCP_SOURCE_ROOTS for read-only market-data or catalog roots, BACKTRADER_MCP_TARGET_ROOTS for generated strategies, and optionally BACKTRADER_MCP_RUNTIMES for verified runtime locations. These values are JSON objects mapping root IDs to absolute paths. Callers use root IDs and relative paths rather than submitting absolute paths.

Run backtrader-mcp doctor before registering the host. A passed diagnostic checks product and dependency versions, configured roots, supported adapters and profiles, and the actual Backtrader module provenance and capabilities. Normal server startup initializes the private state root; the diagnostic itself does not write to source or target roots.

Tools and capabilities

cloudQuant/backtrader-mcp exposes tools for preparing, starting, monitoring, cancelling, and collecting strategy runs. list_jobs enumerates jobs by state, get_run_logs returns bounded and path-sanitized log tails, and list_target_tree provides read-only target preimages for change review. Status responses include a log URI, elapsed time, and bounded ETA information.

Catalog tools provide snapshots, searches, strategy inspection, template listing, and source-attached refreshes. Snapshot entries can be requested in pages, while templates are supplied independently. Tool responses use structured error text with a code and optional next-step suggestion; absolute paths are redacted from errors and job logs.

Limitations and notes

The current implementation is offline and backtest-only. It does not claim MCP Tasks support because the validated SDK version does not provide that extension. The packaged metadata catalog does not include the original source bytes; records can support search and provenance without making inspect_strategy pretend that source is available.

All data and runtime locations must be trusted local paths. A configured runtime must contain backtrader/__init__.py and resolve to github.com/cloudQuant/backtrader. The server is designed for reviewed, bounded runs, not unrestricted code execution or production trading.