backtrader-mcp

Purpose

backtrader-mcp is a standalone, local-first MCP server for building and running reproducible Backtrader strategies. Its goal is to turn restricted CSV files into immutable datasets, typed strategy intents into private drafts, and reviewed drafts into bounded subprocess backtests, while retaining persistent state and reports. In P0, the product is deliberately kept offline and for backtesting only; it does not expose brokers, storage, credentials, live orders, arbitrary Python execution, or network transport.

Main capabilities

• Register restricted CSV files as immutable datasets, with support for normalized column mapping, content-addressed storage, deduplication, and streaming registration.
• Support derived tabular datasets, allowing only four operations: identity, dropna, returns, or sma, with typed parameters and an exact source manifest hash.
• Provide strategy catalog search, with a choice of seven archetypes; support two output configurations: single_test or python_bundle.
• Draft creation, updates, and validation are all based on revision versions and file hashes; the validation stage only parses and compiles the AST, and does not import candidate strategies within the server.
• Separate change approval from run approval, with support for signed tokens, idempotency keys, private local database approval records, and log-style rename transactions.
• Provide five fixed run configurations: runonce, runnext, runonce_runnext_compare, fixed_tests, parameter_sweep; parameter_sweep supports typed parameter grids (up to 64 combinations) and ranks by return_rate.
• Provide observability tools: list_jobs, get_run_logs, list_target_tree; get_run_status reports log_uri, elapsed_seconds, and eta_bound.
• Provide catalog and template tools such as get_catalog_snapshot, search_strategy_catalog, list_strategy_templates.
• The job state machine includes QUEUED, RUNNING, CANCEL_REQUESTED, CANCELLED, SUCCEEDED, FAILED, TIMED_OUT, ORPHANED; every state transition is a compare-and-swap write, and once a terminal state is persisted it is not overwritten.
• The server-owned watchdog consumes worker heartbeats, enforces wall-clock timeout grace, reaps dead orphaned workers, and cleans up detached candidate process groups.
• Jobs report structured error_kind, distinguishing errors such as user strategy, resource limits, timeout, validation, infrastructure, cancellation, and orphan.

Usage

• Requires Python 3.10 or later, MCP Python SDK version satisfying >=2.0.0,<2.1, and uses MCPServer with local stdio.
• Installation method: after creating and activating a dedicated virtual environment, install the package; when checking out from source or when dependencies are skipped, run the explicit installer. The installer only installs Backtrader when it is missing; if another Backtrader distribution is already installed, it leaves it unchanged and returns the installed_backtrader_untrusted warning.
• The runtime root directory must contain backtrader/init.py, and the Git origin must resolve to github.com/cloudquant/backtrader; other forks or the public PyPI package are rejected before the strategy runs.
• Host registration supports Claude Desktop / Claude Code, Codex, OpenCode, OpenClaw, with corresponding example configuration files or commands. All adapters start the same stdio server.
• The first host verification performs MCP initialize, then discovers tools/list, resources/list, prompts/list, and submits a non-mutating request; expects doctor.status=passed, module_file located under the registered runtime, Backtrader version/commit as expected, and catalog entry_count=1155.
• Closed-loop workflow: inspect_dataset → register_dataset → preview_dataset → derive_tabular_dataset → search_strategy_catalog → create_strategy_draft → update_strategy_draft → validate_strategy_draft → list_target_tree → prepare_strategy_changes → local approval → apply_strategy_changes → prepare_strategy_run → local run approval → start_strategy_run → poll get_run_status → optional cancel_strategy_run → get_run_result.
• Approval must be performed via local CLI commands; there is no MCP approval tool, and there is no approved=true parameter. Change approval and run approval must not be mixed up.
• At job startup, the concurrency limit directly rejects rather than queues; when max_concurrent_jobs is reached, actionable suggestions are returned.
• Retention policy: backtrader-mcp clean --kind jobs|cas|drafts|approvals|nonces --before YYYY-MM-DD can respectively clean up finished job records, unreferenced CAS objects, unreferenced drafts, consumed or expired approvals, and consumed token nonces.
• When upgrading to a compatible 0.2.x version, you must stop all connected hosts, back up the private state root, activate the dedicated environment, and reinstall; draft validation tokens, change/run tokens, or approvals must not be reused between incompatible versions.
• Uninstall: first remove the backtrader MCP registration from each host (or delete the matching configuration entries), stop active runs, and then uninstall. Uninstalling the wheel preserves configured state, datasets, generated strategies, and source files.

Applicable Scenarios

Suitable for quantitative research scenarios that require AI-assisted Backtrader strategy development, review, and reproducible runs in a local, offline, backtest-only environment. Suitable for users with requirements for data immutability, approval chains, run traceability, and security.

Limitations

• Deliberately offline and for backtesting only: no broker, storage, credentials, live orders, arbitrary Python execution, or network transmission.
• No MCP approval tool is provided; approval must be completed locally via the CLI.
• Strategy runs only accept the registered CloudQuant Backtrader runtime; other forks or PyPI packages will be rejected.
• Dataset derivation is limited to the four operations identity, dropna, returns, and sma; parameter grids have a maximum of 64 combinations.
• When concurrency reaches the limit, it directly rejects rather than queues.
• The product does not migrate pre-P0 state.
• The documentation states that MCP SDK v2.0.0 does not provide the Tasks extension, so the product does not claim to support that extension.

For more complete documentation (English/Chinese), see https://cloudquant.github.io/backtrader-mcp/ , and it can also be built on Read the Docs, with source files located in docs/ .