Skip to main content
Glama
quant-research-mcp

quant-research-mcp

by FlawlessByte

quant_research_mcp

CI License: MIT Python 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.

Related MCP server: TradeMCP

Tools (13)

Tool

Network

Purpose

quant_list_methods

no

List registered methods (key, paper, timeframe, regimes).

quant_describe_method

no

Full detail + citation for one method.

quant_screen_universe

yes

Rank tickers by gap / rel-volume / ATR%.

quant_compute_indicators

yes

EMA9/20, RSI, ATR, VWAP, Hurst for a ticker.

quant_detect_regime

yes

Hurst → TRENDING / MEAN_REVERTING / RANDOM_WALK.

quant_analyze_setup

yes

Run a per-ticker method → signal + entry/stop/target (+ HTF context).

quant_analyze_universe

yes

Run a universe method: momentum ranking, pairs spread.

quant_backtest_method

yes

Validate a method: replay its own analyze() over history → win rate, expectancy, drawdown, IS/OOS halves.

quant_check_events

yes

Next earnings (+days), ex-dividend — binary-event risk.

quant_portfolio_risk

yes

Stateless heat / correlation / concentration check + candidate verdict.

quant_market_context

yes

SPY/QQQ/IWM, VIX, 11 sectors ranked, risk-on/off breadth.

quant_score_decision

no

Decision helper: setup (+ sentiment, earnings, heat) → score, verdict, size, timeframe-aware execution plan. Deterministic.

quant_fetch_news

yes

Recent headlines (data only; agent forms sentiment).

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)

Key

Timeframe

Paper

hurst_regime_orb

intraday

arXiv:2205.11122 — Hurst regime → ORB / VWAP fade

rsi2_reversion

swing

Connors & Alvarez 2009 — RSI(2) pullback above the 200d SMA

pairs_cointegration

swing

Gatev et al. 2006 — Engle-Granger spread z-score

donchian_trend

position

Faith, Turtle Rules; Moskowitz et al. 2012 — 55d breakout, 20d/ATR trail

xs_momentum

position

Jegadeesh & Titman 1993 — 12-1 cross-sectional momentum, top-N book

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

Target

What it does

make install

uv sync — venv + dependencies

make install-cli

install the quant-research-mcp binary onto your PATH

make uninstall-cli

remove the binary

make dev

install + ruff for linting

make run

run the MCP server (stdio)

make smoke

import + list tools, no network

make test

run the pytest suite (no network)

make inspect

launch the MCP Inspector

make check

tests + lint + assert no LLM/subprocess calls

make register

print the stdio client-config JSON

make claude-add

register the local clone with Claude Code (user scope)

make claude-remove

remove from Claude Code

make build

build sdist + wheel into dist/

make docker-build

build the Docker image locally

make mcpb

pack a Claude Desktop .mcpb bundle

make clean

drop caches, venv and build artifacts

Install

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

Method

Command

Needs

uvx from GitHub (no clone)

uvx --from git+https://github.com/FlawlessByte/quant-research-mcp quant-research-mcp

uv

PyPI

uvx quant-research-mcp · pipx install quant-research-mcp

uv / pipx

Docker

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

Docker

From source

git clone … && cd quant-research-mcp && make install

git + uv

Claude Desktop

install the .mcpb from the latest release

Claude Desktop

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

  2. GHCR: after the first push, set the package visibility to public.

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

Available Tools

13 tools
quant_analyze_setupA
Read-onlyIdempotent

Run a registered method on a ticker to produce a trade setup.

Fetches daily + latest-session intraday data and dispatches to the named method, which returns signal (LONG/SHORT/NO_ENTRY), playbook, regime, and entry/stop/target when actionable.

Args: params (AnalyzeInput): ticker, method_key (default 'hurst_regime_orb'), response_format.

Returns: str: the setup dict (feed it directly to quant_score_decision). Includes signal, playbook, regime, hurst, price, atr_daily, rel_volume, rsi, entry, stop, target, reasons, plus method extras (vwap, or_high, or_low, ema9, ema20). Error string for unknown method or missing data.

Inputs: params (required). Returns: result

quant_analyze_universeA
Read-onlyIdempotent

Run a universe-based method (ranking or pairs) across multiple tickers.

xs_momentum ranks the universe by 12-1 momentum and marks the top-N book LONG. pairs_cointegration requires exactly 2 tickers and returns one setup per leg with the shared spread statistics (beta, ADF p-value, z-score).

Args: params (AnalyzeUniverseInput): method_key, tickers (defaults to the built-in universe), top_n (ranking methods), response_format.

Returns: str: list of setup dicts (each feedable to quant_score_decision). Error string for unknown/non-universe methods or bad ticker counts.

Inputs: params (required). Returns: result

quant_backtest_methodA
Read-onlyIdempotent

Backtest a registered method by replaying its own analyze() over history.

The engines execute the method's live signal logic bar by bar (no separate backtest implementation that could drift). Daily methods replay daily bars with next-open fills and method-specific exits; intraday methods replay each available 5m session (provider-capped to ~60 days); xs_momentum runs a monthly-rebalance portfolio. Costs applied one-way on entry and exit.

Args: params (BacktestInput): method_key, tickers, period, costs_bps, risk_pct, top_n, response_format.

Returns: str: stats (n_trades, win_rate, avg_r/expectancy, profit_factor, max_drawdown_pct, total_return_pct), in-sample/out-of-sample halves, and the last 10 trades. Treat results as PARAMETER VALIDATION, not a forecast — yfinance data is survivorship-prone and costs are estimates.

Inputs: params (required). Returns: result

quant_check_eventsA
Read-onlyIdempotent

Upcoming earnings and dividend events for a ticker.

Earnings inside the holding window are the classic binary risk: pass days_to_earnings into quant_score_decision, which vetoes swing/position entries within the configured window (default 3 days) and warns intraday.

Args: params (TickerInput): ticker, response_format.

Returns: str: {next_earnings, days_to_earnings, recent_earnings, ex_dividend}. Fields are null when the provider has no data — treat unknown as risk and check the company's IR page before a swing entry.

Inputs: params (required). Returns: result

quant_compute_indicatorsA
Read-onlyIdempotent

Compute EMA9/EMA20, RSI, ATR, VWAP and the Hurst exponent for a ticker.

Daily series drive Hurst and ATR; the latest intraday session drives VWAP, EMAs and 5m RSI.

Args: params (TickerInput): ticker, response_format.

Returns: str: a dict with price, hurst, atr_daily, and intraday ema9/ema20/ rsi_5m/vwap. Error string if no data.

Inputs: params (required). Returns: result

quant_describe_methodA
Read-onlyIdempotent

Full detail and citation for one registered method.

Args: params (DescribeMethodInput): method_key plus response_format.

Returns: str: the method's name, paper, paper_url, regime_applicability and a prose description of its mechanics. Error string if the key is unknown (call quant_list_methods for valid keys).

Inputs: params (required). Returns: result

quant_detect_regimeA
Read-onlyIdempotent

Classify a ticker's regime from its daily Hurst exponent.

H >= 0.55 -> TRENDING (momentum edge), H <= 0.45 -> MEAN_REVERTING (fade edge), otherwise RANDOM_WALK (no structural edge).

Args: params (TickerInput): ticker, response_format.

Returns: str: dict with ticker, hurst and regime. Error string if no data.

Inputs: params (required). Returns: result

quant_fetch_newsA
Read-onlyIdempotent

Fetch recent headlines for a ticker. Data only — no sentiment is computed.

The calling agent reads these and forms its own sentiment to pass to quant_score_decision; this tool deliberately does no interpretation.

Args: params (TickerInput): ticker, response_format.

Returns: str: list of headlines, each with title, summary, published, provider. Empty-list message if none found.

Inputs: params (required). Returns: result

quant_list_methodsA
Read-onlyIdempotent

List every registered paper-backed trading method.

Args: params (FormatInput): response_format ('markdown'|'json').

Returns: str: methods with key, name, paper citation, paper_url and regime_applicability. JSON returns the full metadata list; markdown is a readable digest. Use this to discover what method_key values are valid for quant_analyze_setup / quant_describe_method.

Inputs: params (required). Returns: result

quant_market_contextA
Read-onlyIdempotent

Index/VIX/sector tape read for the current session.

SPY/QQQ/IWM day % and 20d-EMA side, VIX level and change, the 11 SPDR sector ETFs ranked by day %, and a breadth flag (risk_on when most sectors advance). Use before sizing any intraday trade; trading breakouts against a risk-off tape is the most common ORB failure mode.

Args: params (FormatInput): response_format.

Returns: str: {indexes, vix, sectors (ranked), breadth{risk_on}}.

Inputs: params (required). Returns: result

quant_portfolio_riskA
Read-onlyIdempotent

Stateless portfolio heat / correlation / concentration check.

Pass your open positions (the server stores nothing) and optionally a candidate trade. Returns per-position and total open risk vs the heat limit, pairwise 90d correlation flags, sector concentration, and for the candidate a FITS / REDUCE / REJECT verdict with a recommended risk_pct to feed into quant_score_decision (with portfolio_heat_pct).

Args: params (PortfolioRiskInput): positions [{ticker, direction, entry, stop, shares}], optional candidate {ticker, direction, entry, stop}, equity, response_format.

Returns: str: heat/correlation/concentration analysis dict; candidate verdict when one was supplied.

Inputs: params (required). Returns: result

quant_score_decisionA
Read-onlyIdempotent

Deterministically score a setup and decide ENTRY / NO_ENTRY.

This is the decision helper: a pure function (no LLM, no network). It combines scientifically-motivated sub-factors — reward:risk, regime strength (|Hurst-0.5|), volume confirmation, RSI positioning and ATR-normalised stop quality — into a 0..1 composite score, gates it against a threshold, applies an optional caller-supplied news-sentiment boost/veto, and returns fixed-fractional position sizing plus a mechanical execution plan. Same inputs always yield the same output.

Args: params (ScoreDecisionInput): setup (from quant_analyze_setup), equity, risk_pct, optional news_sentiment ('bullish'|'bearish'|'neutral') and news_confidence (0..1). The AGENT derives the sentiment from headlines; this tool only consumes it.

Returns: str: dict with verdict (ENTRY|NO_ENTRY), score, threshold, per-factor breakdown, factor_weights, news boost/veto, rationale, position_size (shares, dollar_risk, formula, haircut flag) and, on ENTRY, an execution_plan (entry trigger, order type, stop ladder, profit taking, time stop, abort conditions). 'deterministic': true.

Inputs: params (required). Returns: result

quant_screen_universeA
Read-onlyIdempotent

Rank tickers by intraday tradeability (gap, relative volume, ATR%).

Hard-filters names under $5 or under $50M average daily dollar volume, then scores the rest by 2*|gap%| + rel_volume + 0.5*ATR% and returns the top N.

Args: params (ScreenInput): optional tickers list (defaults to the built-in universe), top_n, response_format.

Returns: str: ranked candidates, each with ticker, price, gap_pct, rel_volume, atr_pct, avg_dollar_volume_m and score. JSON returns a list under 'candidates'; markdown is a ranked table.

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct operation: analysis, backtesting, event checking, indicator computation, method description, regime detection, news fetching, method listing, market context, portfolio risk, decision scoring, and universe screening. No two tools have overlapping purposes.

    Naming Consistency5/5

    All tools follow a consistent 'quant_verb_noun' pattern (e.g., quant_analyze_setup, quant_screen_universe). The naming is predictable and clear, with no mixing of conventions.

    Tool Count5/5

    13 tools is well-scoped for a quantitative research server. Each tool serves a necessary function in the workflow, from analysis to risk management, without being bloated or sparse.

    Completeness4/5

    The tool set covers the core pipeline: screening, analysis, backtesting, risk assessment, and decision scoring. Minor gaps exist (e.g., no direct data export or charting), but these are not essential for the stated purpose of paper-backed trading research.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that exposes trading analytics — technical indicators, portfolio state, risk metrics, and backtest results — as tools an LLM agent can call.
      5
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      MCP server that exposes TradingAgents multi-agent financial research as async tasks, generating research reports and non-executive decisions for LLM hosts without touching trading accounts.
      7
      -