ai-trader: a config-driven Backtrader backtester with an MCP server

What ai-trader actually solves for a quant workflow

Backtrader is a mature event-driven backtesting library, but a strategy is Python code, so every experiment starts with editing a script. ai-trader pushes the parameters out of the code and into YAML. The README describes the project as a "config-driven backtesting framework" built on Backtrader, and the example config shows the split: broker cash and commission, a data file with start_date and end_date, a strategy class name with params, and a sizer block. That file can be committed, diffed and re-run, which is the difference between a reproducible result and a script someone edited last week.

The audience is narrower than the marketing suggests. The pyproject classifier says "Development Status :: 4 - Beta" and requires Python >=3.11,<4.0. The dependency list is a quant stack, not a general-purpose one: backtrader pinned at 1.9.78.123, pandas, numpy, TA-Lib, statsmodels, scipy, plus yfinance and twstock for data. If you are evaluating this as a retail trading bot, the repository does not contain an order router. It backtests.

The mechanism: YAML in, Backtrader engine out, results back

The data flow has four visible stages. A config file is parsed into broker, data, strategy and sizer sections. The data section points at a CSV path such as data/us_stock/TSM.csv, or the CLI fetches that CSV first from yfinance or twstock depending on the market flag. The strategy class is resolved by name from the built-in library of over 20 strategies, or from a custom file placed in ai_trader/backtesting/strategies/classic/, and instantiated with the params from the YAML. Backtrader runs the feed and the sizer, and the result comes back as a Python object when you call the library directly.

The MCP server is a second front end onto the same engine. The README shows it started with python -m ai_trader.mcp, and once registered in Claude Desktop, the assistant calls tools that run a backtest, list strategies or fetch data. Nothing in the README suggests the server exposes a separate execution path; it is a wrapper over the same backtesting calls. That matters for how you reason about it: the MCP surface inherits the limits of the backtester, including the absence of live trading.

SQLite storage is the third piece. The fetch command defaults to CSV; passing --storage sqlite caches the downloaded frame so a repeated fetch reads from disk. The README gives the shape of the win: a first fetch downloads from the API, a repeated fetch loads from cache. It does not publish a benchmark for either path, so treat the speed difference as a design intent rather than a measured figure.

Installing ai-trader and running a first backtest

There are two install paths and they are not equivalent. The pip package is aimed at CLI users and library consumers; the source checkout is what you need for the config examples in config/backtest/ and the scripts in scripts/examples/. Start with the pip route if you only want to run the CLI against your own CSV:

pip install ai-trader

If you want the example configs, clone instead and install with uv, which the README calls the recommended and fastest method:

git clone https://github.com/whchien/ai-trader.git
cd ai-trader
uv sync

Now run a predefined backtest from the repository's example config. This requires the source install, because the config file lives in the checkout:

ai-trader run config/backtest/classic/sma_example.yaml

To test a strategy on your own price file without writing a config, use the quick command. The README's example passes a strategy name, a CSV and an initial cash amount:

ai-trader quick CrossSMAStrategy your_data.csv --cash 100000

Market data comes from the fetch command, which takes a symbol, a market and a start date. The supported market values shown in the README are us_stock, tw_stock and crypto:

ai-trader fetch TSM --market us_stock --start-date 2020-01-01

Add --storage sqlite to cache the download, and use the data subcommands to inspect or prune what is stored:

ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite
ai-trader data list
ai-trader data clean --market us_stock --before 2020-01-01

If you prefer the library over the CLI, the README's simple example imports run_backtest and a strategy class, and passes the strategy params as a dict:

from ai_trader import run_backtest
from ai_trader.backtesting.strategies.classic.sma import CrossSMAStrategy

results = run_backtest(
    strategy=CrossSMAStrategy,
    data_source=None,
    cash=1000000,
    strategy_params={"fast": 10, "slow": 30},
)

With data_source=None the call uses built-in example data, so it is a way to confirm the install before pointing at real files. For the MCP path, the README registers the server as a command with args and a cwd pointing at your checkout:

{
  "mcpServers": {
    "ai-trader": {
      "command": "python3",
      "args": ["-m", "ai_trader.mcp"],
      "cwd": "/path/to/ai-trader"
    }
  }
}

That block goes in claude_desktop_config.json, and the README notes that a virtual environment needs the full interpreter path in the command field, plus a restart of the client.

TA-Lib, GPL-3.0 and the beta label are the real constraints

The dependency list is the first practical obstacle. TA-Lib is pinned at >=0.4.0 and it is a C library with a Python wrapper, not a pure-Python wheel. On a machine without the underlying C headers, the install fails before any strategy runs. The README does not document a fallback, and no alternative indicator backend is listed in pyproject.toml, so this is a hard gate rather than a preference.

The second constraint is the licence. The project is GPL-3.0, and the pyproject classifier states GPLv3+. If you plan to embed the backtester inside a proprietary product, or to ship a modified strategy library without releasing source, the licence is the deciding factor, not the feature list. That is a question for your own counsel; the repository states the terms and nothing more.

The third is maturity. The pyproject classifier is "Development Status :: 4 - Beta", and the version in pyproject.toml is 0.3.4 while the most recent release listed is v0.3.3. The last push to the default branch was on 2026-03-28, roughly six months before today. That is a moderate gap, not abandonment, but it means you should not assume a fast response to a filed bug. The README also does not document rollback or migration between config schema versions, so pinning a version in your own environment is the only guarantee you control.

Where ai-trader is the wrong tool

It does not trade. There is no broker adapter, no order management, no position reconciliation and no live data loop anywhere in the dependency list or the README. If your goal is to put capital at risk automatically, this repository gives you the research half and none of the execution half.

It is also the wrong choice if your strategy logic does not fit the config schema. The YAML covers broker, data, strategy and sizer. A strategy that needs to react to an external signal, size positions from a custom model, or coordinate several instruments in one portfolio will fight the format. The README points to scripts/examples/02_step_by_step.py for step-by-step control, which is the intended escape hatch: drop to the Python API and drive Backtrader yourself. At that point you are using ai-trader mostly for its strategy library and data fetchers, and the config layer stops earning its keep.

Finally, the MCP integration is only as good as the tools it exposes. The README lists three natural-language examples: run a backtest, list strategies, fetch data. Anything outside that list depends on what the server implements, and the README does not enumerate the full tool surface. Do not plan a workflow around a tool you have not confirmed exists.

How ai-trader differs from Zipline and plain Backtrader

The closest comparison is Backtrader itself, since ai-trader is built on it and pins it at 1.9.78.123. With plain Backtrader you write a Cerebro script, add a data feed, add the strategy and call run. ai-trader keeps that engine and puts a config file, a CLI and a strategy registry in front of it. The gain is repeatability and a shorter path from idea to run. The cost is an extra layer whose schema you now have to learn, and a dependency set that includes TA-Lib, fastmcp and sqlmodel that plain Backtrader does not require.

Zipline is the other obvious reference point, and the difference is architectural. Zipline is built around its own data bundle ingestion and a pipeline API for cross-sectional factor work; it expects you to register bundles before you can run anything. ai-trader instead reads a CSV path directly or fetches one through yfinance and twstock, and its config is per-run rather than per-bundle. If your work is single-symbol strategy testing on US, Taiwan or crypto data, the ai-trader shape is lighter. If your work is universe-wide factor screening, Zipline's pipeline model is the one designed for it, and ai-trader has no equivalent.

The MCP server has no counterpart in either. Being able to ask an assistant to run a backtest and read the result is a genuine differentiator, and it is also the newest and least documented part of the project.

Maintenance, upgrades and what the release history shows

The last push to main was on 2026-03-28. The two most recent releases listed are v0.3.3 on 2026-01-05 and 0.3.1 on 2025-12-19. The version string in pyproject.toml is 0.3.4, which is ahead of the latest listed release, so the source tree and the published package are not necessarily at the same point. Check which one you are installing before you file a bug against it.

Upgrade cost is dominated by the pinned dependencies rather than by ai-trader's own code. Backtrader is pinned to an exact version, numpy is capped below 2.0.0, pandas below 3.0.0 and matplotlib below 4.0.0. Those caps protect you from breakage but they also mean you cannot freely move your environment forward without checking whether the caps have been relaxed. The requirements.txt file pins everything to exact versions, including transitive packages, while pyproject.toml uses ranges. If you install from PyPI you get the ranges; if you install from requirements.txt you get the exact set. Pick one and stay with it.

The GPL-3.0 licence travels with the code. Any strategy file you add under ai_trader/backtesting/strategies/ is a derivative work in the ordinary reading of the licence, which is worth understanding before you copy a proprietary signal into that directory. The repository itself gives no additional permissions and no commercial exception.

Editorial conclusion

Adopt ai-trader if you already write Backtrader strategies and want YAML configs, a Click CLI and a way to drive backtests from an MCP client. Do not adopt it if you need a live execution engine, if GPL-3.0 is incompatible with how you ship, or if you cannot install TA-Lib on your platform. Before committing, verify three things: that TA-Lib builds in your environment, that pip install ai-trader gives you the same CLI surface as the source checkout, and that the strategy file you write registers itself in the strategies __init__.py, because the README's manual path mentions that step but does not show the registration line.

Frequently asked questions

Official sources

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