{"id":35686353,"url":"https://github.com/whchien/ai-trader","last_synced_at":"2026-01-07T10:02:48.608Z","repository":{"id":245908677,"uuid":"816848129","full_name":"whchien/ai-trader","owner":"whchien","description":"Backtrader-powered backtesting framework for algorithmic trading, featuring 20+ strategies, multi-market support, CLI tools, and an integrated MCP server for professional traders.","archived":false,"fork":false,"pushed_at":"2025-12-19T13:15:28.000Z","size":10619,"stargazers_count":328,"open_issues_count":0,"forks_count":44,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-01-02T12:38:06.571Z","etag":null,"topics":["ai","ai-agents","algorithmic-trading","backtrader","cli","mcp","mcp-server","portfolio-management","quantitative-finance","stock-price-prediction","trading"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whchien.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-06-18T14:10:24.000Z","updated_at":"2026-01-02T12:26:37.000Z","dependencies_parsed_at":"2024-06-24T19:29:10.202Z","dependency_job_id":"3a4b4660-3bfc-4a44-9384-8f9599f96a7c","html_url":"https://github.com/whchien/ai-trader","commit_stats":null,"previous_names":["whchien/ai-trader"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/whchien/ai-trader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whchien%2Fai-trader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whchien%2Fai-trader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whchien%2Fai-trader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whchien%2Fai-trader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whchien","download_url":"https://codeload.github.com/whchien/ai-trader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whchien%2Fai-trader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28234560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-07T02:00:05.975Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","algorithmic-trading","backtrader","cli","mcp","mcp-server","portfolio-management","quantitative-finance","stock-price-prediction","trading"],"created_at":"2026-01-05T22:00:40.880Z","updated_at":"2026-01-07T10:02:48.603Z","avatar_url":"https://github.com/whchien.png","language":"Python","funding_links":[],"categories":["MCP Servers","📚 Projects (2474 total)"],"sub_categories":["Finance \u0026 Trading","MCP Servers"],"readme":"# AI-Trader\n\n[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-GPL--3.0-green)](LICENSE)\n\n[中文版說明 (Chinese Subpage)](README_zh.md)\n\nA professional, config-driven backtesting framework for algorithmic trading, built on Backtrader. Seamlessly test, optimize, and integrate trading strategies with Large Language Models (LLMs) across stocks, crypto, and forex markets.\n\n![Demo GIF](data/demo.gif)\n\n## Key Features\n\n- **Config-Driven Workflows**: Define and manage backtests with version-controllable YAML files for reproducible results.\n- **Seamless LLM Integration**: Built-in MCP (Model Context Protocol) server allows AI assistants like Claude to run backtests, fetch data, and analyze strategies.\n- **Multi-Market Support**: Test strategies on US stocks, Taiwan stocks, cryptocurrencies, and forex.\n- **Extensive Strategy Library**: Comes with over 20 built-in strategies, from classic indicators to advanced adaptive models.\n- **Powerful CLI**: A rich command-line interface to run backtests, fetch market data, and list strategies.\n- **Developer Friendly**: Easily create and test custom strategies with simple helpers and a clear structure.\n\n## Quick Start\n\n**1. Installation**\n\n**Option A: Install from PyPI (Recommended for using the CLI)**\n```bash\npip install ai-trader\n```\nUse this if you want to:\n- Use the CLI commands: `ai-trader run`, `ai-trader fetch`, `ai-trader quick`\n- Run backtests on your own data files\n- Use as a library in your Python projects\n\n**Option B: Install from Source (Recommended for examples and config templates)**\n```bash\ngit clone https://github.com/whchien/ai-trader.git\ncd ai-trader\npip install -e .\n```\nUse this if you want to:\n- Run the config-based examples in `config/backtest/`\n- Use the example data files in `data/`\n- Run the example scripts in `scripts/examples/`\n- Contribute or customize strategies\n*(Poetry users can run `poetry install`)*\n\n**2. Run a Backtest via CLI**\n\n**If you cloned from source**, run a predefined backtest using a configuration file:\n```bash\n# Run a backtest from a config file (requires source installation)\nai-trader run config/backtest/classic/sma_example.yaml\n```\n\nOr, run a quick backtest on any data file (works with both pip and source installation):\n```bash\n# Quick backtest on your own data file\nai-trader quick CrossSMAStrategy your_data.csv --cash 100000\n```\n\n**3. Fetch Market Data**\n\nDownload historical data for any supported market:\n```bash\n# US Stock\nai-trader fetch TSM --market us_stock --start-date 2020-01-01\n\n# Taiwan Stock (台灣股票)\nai-trader fetch 2330 --market tw_stock --start-date 2020-01-01\n\n# Cryptocurrency\nai-trader fetch BTC-USD --market crypto --start-date 2020-01-01\n```\n\n## Core Workflows\n\n### 1. Configuration-Based Backtesting\n\nThe most robust way to run backtests is with a YAML config file.\n\n**`my_backtest.yaml`:**\n```yaml\nbroker:\n  cash: 1000000\n  commission: 0.001425\n\ndata:\n  file: \"data/us_stock/TSM.csv\"\n  start_date: \"2020-01-01\"\n  end_date: \"2023-12-31\"\n\nstrategy:\n  class: \"CrossSMAStrategy\"\n  params:\n    fast: 10\n    slow: 30\n\nsizer:\n  type: \"percent\"\n  params:\n    percents: 95\n```\n**Run it:**\n```bash\nai-trader run my_backtest.yaml\n```\nSee `config/backtest/` for more examples.\n\n### 2. Python-Based Backtesting\n\nFor more granular control or integration into other Python scripts.\n\n**Simple approach:**\n```python\nfrom ai_trader import run_backtest\nfrom ai_trader.backtesting.strategies.classic.sma import CrossSMAStrategy\n\n# Run backtest with example data\nresults = run_backtest(\n    strategy=CrossSMAStrategy,\n    data_source=None,  # Uses built-in example data\n    cash=1000000,\n    strategy_params={\"fast\": 10, \"slow\": 30}\n)\n```\n\n**Step-by-step control:**\nSee `scripts/examples/02_step_by_step.py` for a detailed example.\n\n### 3. LLM Integration (MCP Server)\n\nRun `ai-trader` as a server to let AI assistants interact with your backtesting engine.\n\n**Start the Server (for testing):**\n```bash\npython -m ai_trader.mcp\n```\n\n**Configure with Claude Desktop (Recommended):**\n\n1. Locate your Claude Desktop configuration file:\n   - **macOS/Linux**: `~/.config/Claude/claude_desktop_config.json`\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the `ai-trader` MCP server to the `mcpServers` section:\n\n```json\n{\n  \"mcpServers\": {\n    \"ai-trader\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"ai_trader.mcp\"],\n      \"cwd\": \"/path/to/ai-trader\"\n    }\n  }\n}\n```\n\n**Configuration Notes:**\n- Replace `/path/to/ai-trader` with your actual ai-trader project directory\n- If using a virtual environment, use the full path to the Python executable: `/path/to/.venv/bin/python3`\n- Restart Claude Desktop after updating the config file\n\nOnce configured, you can use Claude to interact with your backtesting engine with natural language commands like:\n- *\"Run a backtest of the CrossSMAStrategy on TSM data from 2020-2022.\"*\n- *\"List all available trading strategies.\"*\n- *\"Fetch Apple stock data from 2021 to 2024.\"*\n\n## Creating Custom Strategies\n\nCreate a new file in `ai_trader/backtesting/strategies/classic/` and inherit from `BaseStrategy`.\n\n```python\n# ai_trader/backtesting/strategies/classic/my_strategy.py\nimport backtrader as bt\nfrom ai_trader.backtesting.strategies.base import BaseStrategy\n\nclass MyCustomStrategy(BaseStrategy):\n    params = dict(period=20)\n\n    def __init__(self):\n        self.sma = bt.indicators.SMA(self.data.close, period=self.p.period)\n\n    def next(self):\n        if not self.position and self.data.close[0] \u003e self.sma[0]:\n            self.buy()\n        elif self.position and self.data.close[0] \u003c self.sma[0]:\n            self.close()\n```\nThe new strategy is automatically available to the CLI and `run_backtest` function.\n\n## Documentation \u0026 Resources\n\n- **[Strategy Examples](ai_trader/backtesting/strategies/README.md)**: Details on built-in strategies.\n- **[Example Scripts](scripts/examples/)**: 5 complete working examples for different use cases.\n- **[Config Templates](config/backtest/)**: YAML configuration templates.\n- **[Migration Guide](docs/MIGRATION_GUIDE.md)**: For upgrading from v0.1.x.\n\n## Contributing\n\nContributions are welcome! Feel free to report bugs, suggest features, or submit pull requests.\n\n## Show Your Support\n\nIf you find this project helpful, please give it a star !\n\n## License\n\nThis project is licensed under the GNU General Public License v3 (GPL-3.0). See the [LICENSE](LICENSE) file for details.\n ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhchien%2Fai-trader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhchien%2Fai-trader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhchien%2Fai-trader/lists"}