{
  "markdown": "# quant_research_mcp\n\n<!-- mcp-name: io.github.FlawlessByte/quant-research-mcp -->\n\n[![CI](https://github.com/FlawlessByte/quant-research-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/FlawlessByte/quant-research-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-purple.svg)](https://modelcontextprotocol.io/)\n\nAn MCP server exposing a **registry of paper-backed quantitative trading methods**\nplus a **deterministic, no-LLM decision helper**. The server supplies reproducible\nmath (screening, indicators, regime detection, method signals, scored entry\ndecisions); the calling agent supplies judgement (e.g. reading headlines into a\nsentiment signal). No `claude -p`, no subprocess, no LLM inside the server.\n\n> ⚠️ **Not financial advice.** This is read-only **research and educational\n> tooling**. It performs quantitative computation only and **places no orders**.\n> Nothing it outputs is investment advice or a recommendation. Market data may be\n> delayed or wrong, backtests are not forecasts, and trading carries substantial\n> risk of loss. **You alone are responsible for any capital you risk.** Provided\n> \"as is\" without warranty — see [`LICENSE`](LICENSE).\n\n## Why this exists\n\nRepackages a working day-trading pipeline as composable MCP tools, with two goals:\n\n1. **Extensible to future papers.** Each strategy is a `TradingMethod` registered in\n   a registry. Adding a new paper = drop one module, call `register(...)`, import it.\n   Nothing else changes.\n2. **Decision-making is scientific, not generative.** The old pipeline gated entries\n   with an LLM call. Here that is replaced by `quant_score_decision` — a pure\n   function combining reward:risk, regime strength, volume, RSI positioning and\n   ATR-normalised stop quality into an auditable score. Same inputs → same output.\n\n## Tools (13)\n\n| Tool | Network | Purpose |\n|---|---|---|\n| `quant_list_methods` | no | List registered methods (key, paper, timeframe, regimes). |\n| `quant_describe_method` | no | Full detail + citation for one method. |\n| `quant_screen_universe` | yes | Rank tickers by gap / rel-volume / ATR%. |\n| `quant_compute_indicators` | yes | EMA9/20, RSI, ATR, VWAP, Hurst for a ticker. |\n| `quant_detect_regime` | yes | Hurst → TRENDING / MEAN_REVERTING / RANDOM_WALK. |\n| `quant_analyze_setup` | yes | Run a per-ticker method → signal + entry/stop/target (+ HTF context). |\n| `quant_analyze_universe` | yes | Run a universe method: momentum ranking, pairs spread. |\n| `quant_backtest_method` | yes | **Validate a method**: replay its own analyze() over history → win rate, expectancy, drawdown, IS/OOS halves. |\n| `quant_check_events` | yes | Next earnings (+days), ex-dividend — binary-event risk. |\n| `quant_portfolio_risk` | yes | Stateless heat / correlation / concentration check + candidate verdict. |\n| `quant_market_context` | yes | SPY/QQQ/IWM, VIX, 11 sectors ranked, risk-on/off breadth. |\n| `quant_score_decision` | no | **Decision helper**: setup (+ sentiment, earnings, heat) → score, verdict, size, timeframe-aware execution plan. Deterministic. |\n| `quant_fetch_news` | yes | Recent headlines (data only; agent forms sentiment). |\n\nAll tools are read-only and support `response_format: markdown | json`.\n\n## Workflows\n\n**Day trade**\n```\nquant_market_context                  # tape read: risk-on/off, sectors\n  → quant_screen_universe             # find movers\n  → quant_analyze_setup               # hurst_regime_orb on the top name\n  → quant_check_events + quant_fetch_news   # binary risk + agent sentiment\n  → quant_portfolio_risk              # heat/correlation vs your open book\n  → quant_score_decision(setup, news_sentiment, days_to_earnings,\n                         portfolio_heat_pct)\n```\n\n**Swing (days)** — `rsi2_reversion`, `pairs_cointegration` via\n`quant_analyze_setup` / `quant_analyze_universe`; earnings veto matters most\nhere (`quant_check_events` → `days_to_earnings`).\n\n**Position (weeks+)** — `donchian_trend` per ticker, `xs_momentum` over the\nuniverse; re-rank monthly, weekly stop review per the execution plan.\n\n**Before trusting any method**: `quant_backtest_method` on your tickers and\nperiod — it replays the method's own signal logic with costs, and reports\nin-sample vs out-of-sample halves so you can see decay.\n\nThe agent writes any narrative; the server guarantees the numbers.\n\n## The decision helper (`quant_score_decision`)\n\nPure function. Composite score (weights in `config.DECISION_WEIGHTS`):\n\n- **reward_risk** — realised R:R vs the target multiple.\n- **regime_strength** — `|Hurst − 0.5|` scaled (distance from random walk).\n- **volume_confirmation** — relative volume vs the floor.\n- **momentum_position** — RSI in a healthy band for the direction (not exhausted).\n- **stop_quality** — stop distance normalised by daily ATR (noise-tight stops penalised).\n\nOptional `news_sentiment` (the **agent** derives this) boosts an aligned score or\n**vetoes** a contradicted one at confidence ≥ 0.5. Output includes the per-factor\nbreakdown, fixed-fractional `position_size` (with a haircut for noise-tight stops),\nand a mechanically derived `execution_plan` (entry trigger, order type, stop ladder,\nprofit taking, time stop, abort conditions).\n\n## Bundled methods (5)\n\n| Key | Timeframe | Paper |\n|---|---|---|\n| `hurst_regime_orb` | intraday | [arXiv:2205.11122](https://arxiv.org/pdf/2205.11122) — Hurst regime → ORB / VWAP fade |\n| `rsi2_reversion` | swing | Connors & Alvarez 2009 — RSI(2) pullback above the 200d SMA |\n| `pairs_cointegration` | swing | [Gatev et al. 2006](https://doi.org/10.1093/rfs/hhj020) — Engle-Granger spread z-score |\n| `donchian_trend` | position | Faith, Turtle Rules; [Moskowitz et al. 2012](https://www.sciencedirect.com/science/article/pii/S0304405X11002613) — 55d breakout, 20d/ATR trail |\n| `xs_momentum` | position | [Jegadeesh & Titman 1993](https://doi.org/10.1111/j.1540-6261.1993.tb04702.x) — 12-1 cross-sectional momentum, top-N book |\n\n## Data providers\n\nDefault is **yfinance** (free, ~15-min delayed). The data layer sits behind a\nprovider interface (`quant_research_mcp/providers/`): implement the\n`DataProvider` protocol for Alpaca/Polygon/IBKR, register the factory, then run\nwith `QUANT_DATA_PROVIDER=<name>`. All calls are TTL-cached in-process (daily\n15 min, intraday 60 s, news 5 min, events/sector 1 h).\n\n## Adding a future paper\n\n```python\n# quant_research_mcp/methods/my_paper.py\nfrom . import register\nfrom .base import TradingMethod, TradeSetup\n\ndef analyze(daily, session, context) -> TradeSetup:\n    ...  # compute signal, entry, stop, target\n\nregister(TradingMethod(\n    key=\"my_paper_method\",\n    name=\"My Method\",\n    paper=\"Author et al., Title\",\n    paper_url=\"https://arxiv.org/abs/...\",\n    regime_applicability=\"TRENDING\",\n    description=\"One paragraph on the mechanics.\",\n    analyze=analyze,\n))\n```\n\nThen add `from . import my_paper` to `methods/__init__.py`. It now appears in\n`quant_list_methods` and is runnable via `quant_analyze_setup(method_key=...)`.\n\n## Quick start (Makefile)\n\n```bash\nmake install      # create venv + install deps (uv sync)\nmake smoke        # import server, list the 13 tools (no network)\nmake run          # run the server over stdio\nmake help         # list every target\n```\n\n### Install as a shell binary\n\n```bash\nmake install-cli              # installs `quant-research-mcp` onto your PATH (uv tool)\nquant-research-mcp            # runs the server over stdio from anywhere\n```\n\nIf the command isn't found after install, run `uv tool update-shell` and restart\nyour shell (uv's tool bin dir, usually `~/.local/bin`, must be on PATH).\n\n| Target | What it does |\n|---|---|\n| `make install` | `uv sync` — venv + dependencies |\n| `make install-cli` | install the `quant-research-mcp` binary onto your PATH |\n| `make uninstall-cli` | remove the binary |\n| `make dev` | install + ruff for linting |\n| `make run` | run the MCP server (stdio) |\n| `make smoke` | import + list tools, no network |\n| `make test` | run the pytest suite (no network) |\n| `make inspect` | launch the MCP Inspector |\n| `make check` | tests + lint + assert no LLM/subprocess calls |\n| `make register` | print the stdio client-config JSON |\n| `make claude-add` | register the local clone with Claude Code (user scope) |\n| `make claude-remove` | remove from Claude Code |\n| `make build` | build sdist + wheel into `dist/` |\n| `make docker-build` | build the Docker image locally |\n| `make mcpb` | pack a Claude Desktop `.mcpb` bundle |\n| `make clean` | drop caches, venv and build artifacts |\n\n## Install\n\nEvery method runs the same stdio server — pick whichever fits your setup.\n\n| Method | Command | Needs |\n|---|---|---|\n| **uvx from GitHub** (no clone) | `uvx --from git+https://github.com/FlawlessByte/quant-research-mcp quant-research-mcp` | [uv](https://docs.astral.sh/uv/) |\n| **PyPI** | `uvx quant-research-mcp` · `pipx install quant-research-mcp` | uv / pipx |\n| **Docker** | `docker run -i --rm ghcr.io/flawlessbyte/quant-research-mcp` | Docker |\n| **From source** | `git clone … && cd quant-research-mcp && make install` | git + uv |\n| **Claude Desktop** | install the `.mcpb` from the [latest release](https://github.com/FlawlessByte/quant-research-mcp/releases) | Claude Desktop |\n\n> PyPI and Docker images are published on tagged releases; until the first\n> release, use the **uvx from GitHub** or **from source** rows.\n\n## Use with Claude Code\n\nFastest — runs straight from GitHub, no clone:\n\n```bash\nclaude mcp add quant_research -- \\\n  uvx --from git+https://github.com/FlawlessByte/quant-research-mcp quant-research-mcp\n```\n\nAfter a PyPI release this shortens to:\n\n```bash\nclaude mcp add quant_research -- uvx quant-research-mcp\n```\n\nContainerised:\n\n```bash\nclaude mcp add quant_research -- docker run -i --rm ghcr.io/flawlessbyte/quant-research-mcp\n```\n\nFrom a local clone (development): `make claude-add` registers this checkout at\nuser scope; `make register` prints a paste-ready `.mcp.json` block.\n\n**Verify** inside Claude Code:\n\n```\n/mcp                       # should list 'quant_research' as connected\n```\n\nThen ask e.g. *\"screen the universe and analyze the top name with the hurst\nmethod, then score the entry decision.\"* It will call `quant_screen_universe`\n→ `quant_analyze_setup` → `quant_score_decision`.\n\n## From source (development)\n\n```bash\ngit clone https://github.com/FlawlessByte/quant-research-mcp\ncd quant-research-mcp\nmake install      # uv sync — venv + dependencies\nmake smoke        # list the 13 tools (no network)\nmake test         # 40 offline tests\n```\n\nOptional: `make install-cli` puts a `quant-research-mcp` binary on your PATH\n(via `uv tool`). If it isn't found afterwards, run `uv tool update-shell` and\nrestart your shell. Inspect tool schemas with `make inspect`.\n\n## Releasing (maintainers)\n\nCI runs ruff + the 40 offline tests on every push/PR (Python 3.12 & 3.13).\nCutting a release is tag-driven:\n\n```bash\n# bump version in pyproject.toml + server.json + manifest.json, commit, then:\ngit tag v0.1.0 && git push origin v0.1.0\n```\n\nThat fires two workflows:\n\n- **`release.yml`** → `uv build`, publish to **PyPI** via Trusted Publishing\n  (OIDC, no stored token), and attach the wheel/sdist + a `.mcpb` bundle to the\n  GitHub Release.\n- **`docker.yml`** → build and push `ghcr.io/flawlessbyte/quant-research-mcp`.\n\nOne-time setup:\n\n1. **PyPI:** create the project and add a Trusted Publisher (owner `FlawlessByte`,\n   repo `quant-research-mcp`, workflow `release.yml`, environment `pypi`).\n2. **GHCR:** after the first push, set the package visibility to public.\n3. **MCP registry:** after the first PyPI release, list it with the\n   [`mcp-publisher`](https://github.com/modelcontextprotocol/registry) CLI —\n   `mcp-publisher login github` then `mcp-publisher publish` (uses `server.json`;\n   GitHub login proves ownership of the `io.github.FlawlessByte/…` namespace).\n\n> The Claude Desktop `.mcpb` invokes `uvx` under the hood, so a one-click install\n> still requires [uv](https://docs.astral.sh/uv/) on the machine — bundling\n> pandas/scipy/statsmodels wheels directly would be large and platform-specific.\n\n## Limitations (what a serious trader still needs elsewhere)\n\n- **Delayed data** until you wire a real-time provider key (interface is ready;\n  yfinance is ~15-min delayed and its news feed is thin).\n- **No macro calendar** (FOMC/CPI/NFP) — no reliable free feed; pass your own\n  judgement through `news_sentiment` / `news_confidence`.\n- **No options data** (IV, term structure, gamma levels), no short\n  interest/float, no Level 2 — next frontier.\n- **Backtests are parameter validation, not forecasts**: yfinance history has\n  survivorship bias, costs are estimates, intraday replay is capped at ~60 days\n  of 5m bars by the provider.\n- **No persistence** by design — the server stores nothing; supply open\n  positions per call (`quant_portfolio_risk`). A trade journal is a planned\n  opt-in module.\n",
  "bytes": 13087,
  "sha": "f4a0336f11a6ef1901cb008de72fc514f1eea9f580b5fb0fa7fb3b2f254ea0d2",
  "repo_slug": "flawlessbyte/quant-research-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_flawlessbyte_quant_research_mc_2be22f76/readme"
}