ai-trader: A Config-Driven Backtrader Wrapper With an MCP Server

The Gap ai-trader Fills Between Backtrader and a Repeatable Run

Backtrader gives you a Cerebro engine and a strategy class. It does not give you a file format for a backtest, a command to download price history, or a way for an assistant to start a run. ai-trader adds those three things on top. The README describes it as a "config-driven backtesting framework for algorithmic trading, built on Backtrader", and the audience it names is professional traders who want to "test, optimize, and integrate trading strategies with Large Language Models". The practical target is narrower than that sentence. This is for a Python developer who already knows what a moving average crossover is, wants the parameters of that crossover in version control rather than in a notebook cell, and wants the same run to be startable from a shell or from Claude Desktop. If you have never written a Backtrader strategy, the twenty-plus bundled strategies are useful reading material before they are useful tooling.

What Actually Happens When You Run ai-trader run

The README shows a YAML file with four top-level keys: broker, data, strategy, sizer. broker carries cash and commission. data carries a file path plus start_date and end_date. strategy carries a class name and a params mapping. sizer carries a type and its own params, with percent and a percents value of 95 in the example. Running ai-trader run my_backtest.yaml reads that file and hands the pieces to Backtrader. The data path in the example points at data/us_stock/TSM.csv, which is a local file, so the framework is not fetching anything at run time. That separation matters: fetch and run are distinct commands, and the config references the artefact that fetch produced. The strategy key resolves to a class such as CrossSMAStrategy, and the example imports that class from ai_trader.backtesting.strategies.classic.sma in the Python API, which tells you the classic strategies live in a package path with a classic subdirectory. The README also mentions an __init__.py registration step in the custom strategy workflow, so strategy discovery is import-based rather than a plugin registry you configure separately.

The CLI Surface: run, quick, fetch, data

Four commands are documented. ai-trader run takes a YAML path. ai-trader quick takes a strategy name, a CSV path, and a --cash flag, which is the path for a one-off test against data you already have. ai-trader fetch takes a symbol, a --market value, a --start-date, and optionally --storage. Documented market values are us_stock, tw_stock, and crypto. The README's examples use TSM, 2330, BTC-USD, and AAPL, and the description also lists forex, though no forex fetch example appears in the material supplied. ai-trader data has list, info, and clean subcommands, and clean accepts --market and --before. The --storage flag accepts csv (the default), sqlite, or both. The README states that a first SQLite fetch downloads from the API and caches, giving a figure of roughly two to three seconds, and that a repeated fetch loads from cache in roughly 50 milliseconds with no API call. Those two numbers are the project's own claims, not measurements I can confirm. Treat them as an order-of-magnitude hint about what caching buys you, and nothing more.

The MCP Server and What It Exposes to an Assistant

The MCP integration is the part that distinguishes this project from the many Backtrader wrappers on GitHub. You start it with python -m ai_trader.mcp, or you register it in Claude Desktop's config file under mcpServers with a command of python3, args of ["-m", "ai_trader.mcp"], and a cwd pointing at the project directory. The README notes that if you use a virtual environment you should point at the full interpreter path such as /path/to/.venv/bin/python3, and that Claude Desktop must be restarted after the config change. The documented capabilities are running a backtest, listing strategies, fetching data, and analysing strategies, triggered by natural-language requests. This is a thin control surface over the same functions the CLI calls. It is not a model that predicts prices, despite the stock-price-prediction topic tag on the repository. If you were expecting a forecasting component, the README does not describe one.

Where the Documentation Stops Being Enough

The README is honest about installation paths and thin everywhere else. Two installation routes are given, and they are not equivalent. The PyPI route supports the CLI and library use. The source route is what you need for config/backtest/ examples, the data/ example files, and scripts/examples/. The README says so directly, which is better than most projects manage. What it does not give you is a data schema. There is no statement of which columns a CSV must contain for ai-trader quick or for a data.file entry, no statement of whether adjusted or unadjusted prices are used, and no statement of how the end_date boundary is treated. Those are the questions that decide whether a backtest is meaningful, and they are unanswered in the supplied material. There is also no live trading or broker execution path anywhere in the README. It is a backtester, and the MCP server runs backtests. Anyone reading "algorithmic trading" as "connects to my broker" will be disappointed. Finally, the strategy creation workflow leans on a Claude Code /add-strategy skill, which is convenient if you use that tool and adds a dependency on it if you do not. The manual path exists, but the README's example of it is truncated mid-file, so you are left inferring the BaseStrategy contract from the classic strategies themselves.

SQLite Caching, Versioning, and the Upgrade Bill

The SQLite option is the most concrete engineering decision in the project. Fetching to CSV means every backtest re-reads a file; fetching to SQLite means the download happens once and later runs read from a local store, with data list, data info, and data clean to manage it. For anyone iterating on strategy parameters across a few years of daily bars, that is the difference between a run loop you tolerate and one you avoid. It also creates a second source of truth: a stale SQLite cache and a fresh CSV for the same symbol can disagree, and the README does not describe how the two are reconciled when --storage both is used. On maintenance, the release history shows v0.3.3 in January 2026 and 0.3.1 in December 2025, with the last push in March 2026, so this is a project under active change rather than a frozen one. Expect the CLI and config keys to move between minor versions, and pin the version in your own environment. The GPL-3.0 licence is the constraint worth reading carefully: it is a copyleft licence, and if you build ai-trader into something you distribute, the terms of that distribution change. I am not your lawyer and this is not legal advice. If your organisation has a policy against copyleft dependencies in shipped products, check it before you write strategies against this rather than after.

ai-trader Against a Plain Backtrader Script

The real alternative is not another framework. It is forty lines of Backtrader you write yourself. A plain script gives you full control over data loading, the exact column names, the commission model, and the analyser output, and it has no YAML layer to learn and no version to pin. What you lose is everything ai-trader exists to provide: the config file that a colleague can read and diff, the fetch command with a cache behind it, the twenty-plus strategies you can read for reference, and the MCP server that lets an assistant start a run without you opening a terminal. The trade is legibility and reuse against control and transparency. If you run one strategy on one instrument once, write the script. If you run the same strategy across TSM, 2330, and BTC-USD with different cash and commission settings, the YAML layer earns its place, because the alternative is copy-pasting a script five times and letting the copies drift. Vectorised backtesting libraries are a different comparison and not a substitute here: they reimplement the event loop, whereas ai-trader keeps Backtrader's, which means your existing strategy classes and indicators still work.

Who Should Install This, and What to Check Before Trusting a Number

Install it if you have Backtrader strategies in a repository, you want their parameters in YAML under version control, and you want a fetch-and-cache step that does not involve you writing a data loader. Install it if you want Claude Desktop or another MCP client to be able to trigger a run. Do not install it if you need order execution against a live broker, if you need a documented and stable CSV contract before you commit, or if GPL-3.0 is incompatible with your distribution plans. The verification step that matters is small and specific. Run ai-trader fetch on one symbol with --storage csv, open the resulting file, and confirm the column names and date range match what your strategy expects. Then run ai-trader quick with a bundled strategy on that file, and separately run the same strategy through Backtrader directly with the same cash and commission, and compare the final portfolio value and trade count. If those two numbers match, the wrapper is doing what it claims and you can build on it. If they do not, the discrepancy is in the config-to-Cerebro translation, and that is the layer you would be trusting for every subsequent result.

Editorial conclusion

Adopt ai-trader if you already write Backtrader strategies and want YAML configs, a fetch CLI, and an MCP entry point without building them yourself, and if GPL-3.0 fits how you ship code. Skip it if you need a live trading path, a documented data schema, or a permissive licence, because the README shows none of those. Verify first that ai-trader fetch writes the CSV column layout your own strategies expect, and that ai-trader run reproduces a result you computed by hand in plain Backtrader.

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. whchien/ai-trader on GitHub