quant_research_mcp

<!-- mcp-name: io.github.FlawlessByte/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.

1. 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

From a local clone (development): make claude-add registers this checkout at user scope; make register prints a paste-ready .mcp.json block.

Verify inside Claude Code:

/mcp                       # should list 'quant_research' as connected

Then ask e.g. "screen the universe and analyze the top name with the hurst method, then score the entry decision." It will call quant_screen_universe → quant_analyze_setup → quant_score_decision.

From source (development)

git clone https://github.com/FlawlessByte/quant-research-mcp
cd quant-research-mcp
make install      # uv sync — venv + dependencies
make smoke        # list the 13 tools (no network)
make test         # 40 offline tests

Optional: make install-cli puts a quant-research-mcp binary on your PATH (via uv tool). If it isn't found afterwards, run uv tool update-shell and restart your shell. Inspect tool schemas with make inspect.

Releasing (maintainers)

CI runs ruff + the 40 offline tests on every push/PR (Python 3.12 & 3.13). Cutting a release is tag-driven:

# bump version in pyproject.toml + server.json + manifest.json, commit, then:
git tag v0.1.0 && git push origin v0.1.0

That fires two workflows:

• `release.yml` → uv build, publish to PyPI via Trusted Publishing

(OIDC, no stored token), and attach the wheel/sdist + a .mcpb bundle to the GitHub Release.

• `docker.yml` → build and push ghcr.io/flawlessbyte/quant-research-mcp.

One-time setup:

1. PyPI: create the project and add a Trusted Publisher (owner FlawlessByte,

repo quant-research-mcp, workflow release.yml, environment pypi).

1. GHCR: after the first push, set the package visibility to public.
2. MCP registry: after the first PyPI release, list it with the

mcp-publisher CLI — mcp-publisher login github then mcp-publisher publish (uses server.json; GitHub login proves ownership of the io.github.FlawlessByte/… namespace).

The Claude Desktop .mcpb invokes uvx under the hood, so a one-click install still requires uv on the machine — bundling pandas/scipy/statsmodels wheels directly would be large and platform-specific.

Limitations (what a serious trader still needs elsewhere)

• Delayed data until you wire a real-time provider key (interface is ready;

yfinance is ~15-min delayed and its news feed is thin).

• No macro calendar (FOMC/CPI/NFP) — no reliable free feed; pass your own

judgement through news_sentiment / news_confidence.

• No options data (IV, term structure, gamma levels), no short

interest/float, no Level 2 — next frontier.

• Backtests are parameter validation, not forecasts: yfinance history has

survivorship bias, costs are estimates, intraday replay is capped at ~60 days of 5m bars by the provider.

• No persistence by design — the server stores nothing; supply open

positions per call (quant_portfolio_risk). A trade journal is a planned opt-in module.