Quant research for US stocks, built to live inside your AI assistant. Plug it into Claude or Codex via MCP and ask about any ticker — get explainable ratings, key levels, and the reasoning, then discuss it in the same chat. Also works as a one-command CLI.
English | 中文
quant.ai is a command-line quant-research toolkit for US equities, built for everyday investors. Type one command and get an explainable rating, key support/stop levels, and the reasoning behind them — all derived from historical prices, fully offline-friendly, and with no brokerage attached.
⚠️ Research only — not investment advice. It never places or suggests live orders. Output is English by default; add--lang zh(or pick atquant-ai init) for Chinese (中文).
pip install -e . # or: pip install -r requirements.txt
quant-ai doctor # environment self-check (deps + data connectivity)
quant-ai analyze AAPL # rate one stock in secondsNo entry point? python -m quant_agent analyze AAPL works the same.
Real output from quant-ai analyze AAPL — English by default, --lang zh for Chinese. Ratings range from Strong Buy through Neutral to Strong Sell. Add --output-dir to export Markdown + JSON, or --chart for a PNG chart.
The headline feature — expose quant.ai as an MCP server and let your AI assistant call it:
claude mcp add quant-research -- python -m quant_agent.mcp_serverThen just ask, in the same chat where you work:
"What's the read on NVDA?" · "Watch TSLA for me." · "I bought 15 AAPL at 182.5 — track it." · "How are my positions doing?" · "Generate today's market report."
Claude (or Codex) calls into real project data, shows you the quant analysis, and you discuss it inline — no separate website, no copy-pasting. The daily report opens with your holdings P&L and renders as a polished HTML artifact. See the manual (Chinese) for Claude Desktop / Codex config.
Let your AI assistant install it — paste this into Claude Code (or any AI CLI) and it can set everything up:
Install https://github.com/TingdeLiu/quant.ai as an MCP server:
1. git clone https://github.com/TingdeLiu/quant.ai && cd quant.ai
2. pip install -e .
3. claude mcp add quant-research -- python -m quant_agent.mcp_server
4. Verify: `claude mcp list` should show quant-research ✓ connected
- 🤖 Lives inside your AI assistant — the headline feature. Plug the built-in MCP server into Claude or Codex and ask "what's the read on NVDA?" It pulls real quant analysis from this project, so you see the analysis and discuss it in one conversation. Most stock-analysis tools are standalone websites — this one is embedded in the AI you already chat with.
- 💼 Your watchlist & holdings, managed by chat. Tell Claude "watch NVDA" or "I bought 15 AAPL at 182.5" — they persist locally in
data/portfolio.json, are folded into every analysis automatically, and the daily report opens with your positions and unrealized P&L (best-effort live quotes, falling back to last close). - 🖼️ Artifact-ready daily report — the market brief ships as a self-contained light/dark HTML file that Claude renders as an inline artifact; Markdown and JSON are written alongside for everything else.
- 🎯 Zero-config single-stock analysis —
analyze AAPLreturns rating, returns, RSI, volatility, MA positions, support/stop levels, and human-readable reasons. - 🧩 Personalized watchlist —
quant-ai initbuilds a universe that is 2/3 your own picks (companies + sectors you care about) and 1/3 discovered by the engine from the wider market. - 🔬 Research backtests — cross-sectional signals (12-1 momentum, 20/50 trend, 1-month reversal, low-vol), signal-weight search, walk-forward stability analysis, plus SPY and equal-weight baselines to separate alpha from beta.
- 📊 Local console — one page, four tabs (report / markets / backtest diagnostics / ops), served locally with no API key anywhere in the stack.
- 🛡️ Safe by design — deterministic signals + risk layer, friendly degradation on network/data errors, paper trading only — never submits real orders.
quant-ai market-report builds a daily US-equity research brief in an Anthropic-style design, written four ways: a full HTML page, a self-contained artifact fragment, Markdown and JSON. It is a single page with four tabs — Holdings, Market, Ideas, News — switched by pure CSS, so they still work inside an AI client's sandboxed artifact view.
The brief opens with your P&L: market value, unrealized gain, day P&L, and a sparkline per position (best-effort live quotes, falling back to the last close). Right under it, Holdings at a glance gives each position its own card — portfolio weight, trend state, 5D/1M/3M returns, annualized volatility, 1-year max drawdown, distance from the 52-week high, strength against the benchmark, the sell-side analyst range, where it stands in the quant lists, its recent headlines, and a click-to-expand 1W–5Y close chart.
That section deliberately stops at the facts. It carries no buy/sell call and no price forecast — a test asserts the wording never drifts. This is a research tool, not a licensed adviser: it lays out the evidence and leaves the decision to you.
The per-holding news blurbs are hand-written and read from data/news_digest.json ({as_of, digests: {SYMBOL: "one line"}}) — the project never calls an LLM API for them. When that file's as_of is older than the report's data date, each card is stamped "digest as of …", so a stale summary can't pass itself off as today's.
Rather than just quoting the index: the benchmark's day/5D/1M/3M returns next to its distance from the 52-week high, drawdown and volatility; a VIX risk gauge with its trailing-year percentile; breadth meters — share of names advancing over 5D/1M and share holding above their 20D/50D moving averages, counted over your single stocks only, so a dozen index ETFs can't flatter the reading; sector rotation across the eleven SPDR sector ETFs, ranked by 1-month move with their excess over the benchmark; and a fund tracker grouped into broad indices, themes (semis, AI) and cross-asset (VIX, long Treasuries, gold, the dollar, crude) for where the money is going outside equities.
Research picks split by holding horizon (long / medium / short), each with the analyst valuation-range bar, day change, risk and confidence tags — positions you already hold are pinned to the top and highlighted. Below them, the potential picks and high risk tables spell out the statistical reason each name qualified. Index and sector ETFs are excluded from both lists.
quant-ai serve-dashboard serves one local page with four tabs — report, markets, backtest diagnostics and ops — reusing the report's own styling instead of a second design. write-dashboard writes the backtest-diagnostics page on its own, next to a run's outputs. The page language follows language: in your config.
| Command | What it does |
|---|---|
quant-ai analyze AAPL MSFT NVDA |
Rate one or more stocks |
quant-ai analyze --file watchlist.txt |
Rate symbols from a file |
quant-ai init |
Build a personalized watchlist (interactive) |
quant-ai analyze --watchlist |
Rate your personalized watchlist |
quant-ai run-backtest --config configs/default.yaml |
Run the research backtest |
quant-ai market-report |
Generate the daily market-intel report |
quant-ai serve-dashboard |
Start the local console (report / markets / backtest / ops) |
quant-ai doctor |
Environment self-check |
- Data — daily OHLCV from Yahoo Finance (
yfinance) by default, or local CSV/Parquet. Cached and validated. - Signals — cross-sectional, point-in-time-lagged factors, z-scored per day.
- Portfolio & risk — deterministic target weights under position/turnover/liquidity limits.
- Evaluation — train / validation / test split, walk-forward windows, and benchmark-relative metrics (Sharpe, Sortino, Calmar, max drawdown, alpha/beta).
- AI — the project calls no LLM API of its own. It ships facts you can check: quantitative statistics, rule-based ratings, and third-party consensus. Synthesis and discussion happen in whichever AI client the MCP server is mounted in, so there is no API key, no extra cost, and no second model between you and the data.
- Full manual (Chinese): docs/manual_zh.md — detailed config, backtest/walk-forward, dashboard API, MCP integration, output files.
- Changelog: CHANGELOG.md · Contributing: CONTRIBUTING.md · Roadmap: roadmap.md
python -m pytest # 106 tests, network-free
python -m ruff check quant_agent tests conftest.pyThis project is for quantitative research and education only. It analyzes historical prices and produces research signals — not investment advice, and not authorization to trade. Markets carry risk; you are responsible for your own decisions.