# cloudQuant/backtrader-mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/cloudQuant/backtrader-mcp  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cloudquant-backtrader-mcp

## Description
Build and run reproducible Backtrader backtests from local CSV data, with human-gated runs, logs and JSON/Markdown reports. Offline and backtest-only.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/cloudquant-backtrader-mcp/readme_