quant_research_mcp

An MCP server exposing a registry of paper-backed quantitative trading methods plus a deterministic, no-LLM decision helper. The server supplies reproducible math (screening, indicators, regime detection, method signals, scored entry decisions); the calling agent supplies judgement (e.g. reading headlines into a sentiment signal). No claude -p, no subprocess, no LLM inside the server.

⚠️ Not financial advice. This is read-only research and educational tooling. It performs quantitative computation only and places no orders. Nothing it outputs is investment advice or a recommendation. Market data may be delayed or wrong, backtests are not forecasts, and trading carries substantial risk of loss. You alone are responsible for any capital you risk. Provided "as is" without warranty — see LICENSE.

Why this exists

Repackages a working day-trading pipeline as composable MCP tools, with two goals:

1. Extensible to future papers. Each strategy is a TradingMethod registered in a registry. Adding a new paper = drop one module, call register(...), import it. Nothing else changes.
2. Decision-making is scientific, not generative. The old pipeline gated entries with an LLM call. Here that is replaced by quant_score_decision — a pure function combining reward:risk, regime strength, volume, RSI positioning and ATR-normalised stop quality into an auditable score. Same inputs → same output.

Tools (13)

All tools are read-only and support response_format: markdown | json.

Workflows

Day trade

quant_market_context                  # tape read: risk-on/off, sectors
  → quant_screen_universe             # find movers
  → quant_analyze_setup               # hurst_regime_orb on the top name
  → quant_check_events + quant_fetch_news   # binary risk + agent sentiment
  → quant_portfolio_risk              # heat/correlation vs your open book
  → quant_score_decision(setup, news_sentiment, days_to_earnings,
                         portfolio_heat_pct)

Swing (days) — rsi2_reversion, pairs_cointegration via quant_analyze_setup / quant_analyze_universe; earnings veto matters most here (quant_check_events → days_to_earnings).

Position (weeks+) — donchian_trend per ticker, xs_momentum over the universe; re-rank monthly, weekly stop review per the execution plan.

Before trusting any method: quant_backtest_method on your tickers and period — it replays the method's own signal logic with costs, and reports in-sample vs out-of-sample halves so you can see decay.

The agent writes any narrative; the server guarantees the numbers.

The decision helper (quant_score_decision)

Pure function. Composite score (weights in config.DECISION_WEIGHTS):

• reward_risk — realised R:R vs the target multiple.
• regime_strength — |Hurst − 0.5| scaled (distance from random walk).
• volume_confirmation — relative volume vs the floor.
• momentum_position — RSI in a healthy band for the direction (not exhausted).
• stop_quality — stop distance normalised by daily ATR (noise-tight stops penalised).

Optional news_sentiment (the agent derives this) boosts an aligned score or vetoes a contradicted one at confidence ≥ 0.5. Output includes the per-factor breakdown, fixed-fractional position_size (with a haircut for noise-tight stops), and a mechanically derived execution_plan (entry trigger, order type, stop ladder, profit taking, time stop, abort conditions).

Bundled methods (5)

Data providers

Default is yfinance (free, ~15-min delayed). The data layer sits behind a provider interface (quant_research_mcp/providers/): implement the DataProvider protocol for Alpaca/Polygon/IBKR, register the factory, then run with QUANT_DATA_PROVIDER=<name>. All calls are TTL-cached in-process (daily 15 min, intraday 60 s, news 5 min, events/sector 1 h).

Adding a future paper

# quant_research_mcp/methods/my_paper.py
from . import register
from .base import TradingMethod, TradeSetup

def analyze(daily, session, context) -> TradeSetup:
    ...  # compute signal, entry, stop, target

register(TradingMethod(
    key="my_paper_method",
    name="My Method",
    paper="Author et al., Title",
    paper_url="https://arxiv.org/abs/...",
    regime_applicability="TRENDING",
    description="One paragraph on the mechanics.",
    analyze=analyze,
))

Then add from . import my_paper to methods/__init__.py. It now appears in quant_list_methods and is runnable via quant_analyze_setup(method_key=...).

Quick start (Makefile)

make install      # create venv + install deps (uv sync)
make smoke        # import server, list the 13 tools (no network)
make run          # run the server over stdio
make help         # list every target

Install as a shell binary

make install-cli              # installs `quant-research-mcp` onto your PATH (uv tool)
quant-research-mcp            # runs the server over stdio from anywhere

If the command isn't found after install, run uv tool update-shell and restart your shell (uv's tool bin dir, usually ~/.local/bin, must be on PATH).

Install

Every method runs the same stdio server — pick whichever fits your setup.

PyPI and Docker images are published on tagged releases; until the first release, use the uvx from GitHub or from source rows.

Use with Claude Code

Fastest — runs straight from GitHub, no clone:

claude mcp add quant_research -- \
  uvx --from git+https://github.com/FlawlessByte/quant-research-mcp quant-research-mcp

After a PyPI release this shortens to:

claude mcp add quant_research -- uvx quant-research-mcp

Containerised:

claude mcp add quant_research -- docker run -i --rm ghcr.io/flawlessbyte/quant-research-mcp