quant-research-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@quant-research-mcp analyze setup for AAPL using hurst_regime_orb"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Extensible to future papers. Each strategy is a
TradingMethodregistered in a registry. Adding a new paper = drop one module, callregister(...), import it. Nothing else changes.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 |
| no | List registered methods (key, paper, timeframe, regimes). |
| no | Full detail + citation for one method. |
| yes | Rank tickers by gap / rel-volume / ATR%. |
| yes | EMA9/20, RSI, ATR, VWAP, Hurst for a ticker. |
| yes | Hurst → TRENDING / MEAN_REVERTING / RANDOM_WALK. |
| yes | Run a per-ticker method → signal + entry/stop/target (+ HTF context). |
| yes | Run a universe method: momentum ranking, pairs spread. |
| yes | Validate a method: replay its own analyze() over history → win rate, expectancy, drawdown, IS/OOS halves. |
| yes | Next earnings (+days), ex-dividend — binary-event risk. |
| yes | Stateless heat / correlation / concentration check + candidate verdict. |
| yes | SPY/QQQ/IWM, VIX, 11 sectors ranked, risk-on/off breadth. |
| no | Decision helper: setup (+ sentiment, earnings, heat) → score, verdict, size, timeframe-aware execution plan. Deterministic. |
| 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 |
| intraday | arXiv:2205.11122 — Hurst regime → ORB / VWAP fade |
| swing | Connors & Alvarez 2009 — RSI(2) pullback above the 200d SMA |
| swing | Gatev et al. 2006 — Engle-Granger spread z-score |
| position | Faith, Turtle Rules; Moskowitz et al. 2012 — 55d breakout, 20d/ATR trail |
| 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 targetInstall 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 anywhereIf 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 |
|
|
| install the |
| remove the binary |
| install + ruff for linting |
| run the MCP server (stdio) |
| import + list tools, no network |
| run the pytest suite (no network) |
| launch the MCP Inspector |
| tests + lint + assert no LLM/subprocess calls |
| print the stdio client-config JSON |
| register the local clone with Claude Code (user scope) |
| remove from Claude Code |
| build sdist + wheel into |
| build the Docker image locally |
| pack a Claude Desktop |
| 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) |
| |
PyPI |
| uv / pipx |
Docker |
| Docker |
From source |
| git + uv |
Claude Desktop | install the | 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-mcpAfter a PyPI release this shortens to:
claude mcp add quant_research -- uvx quant-research-mcpContainerised:
claude mcp add quant_research -- docker run -i --rm ghcr.io/flawlessbyte/quant-research-mcpFrom 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 connectedThen 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 testsOptional: 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.0That fires two workflows:
release.yml→uv build, publish to PyPI via Trusted Publishing (OIDC, no stored token), and attach the wheel/sdist + a.mcpbbundle to the GitHub Release.docker.yml→ build and pushghcr.io/flawlessbyte/quant-research-mcp.
One-time setup:
PyPI: create the project and add a Trusted Publisher (owner
FlawlessByte, repoquant-research-mcp, workflowrelease.yml, environmentpypi).GHCR: after the first push, set the package visibility to public.
MCP registry: after the first PyPI release, list it with the
mcp-publisherCLI —mcp-publisher login githubthenmcp-publisher publish(usesserver.json; GitHub login proves ownership of theio.github.FlawlessByte/…namespace).
The Claude Desktop
.mcpbinvokesuvxunder 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 toolsquant_analyze_setupARead-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_universeARead-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_methodARead-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_eventsARead-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_indicatorsARead-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_methodARead-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_regimeARead-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_newsARead-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_methodsARead-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_contextARead-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_riskARead-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_decisionARead-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_universeARead-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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Research-only MCP server: your AI as a quant research desk. 90 tools, no trades, no brokers.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
MCP server exposing the Backtest360 engine API as tools for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables quant research, strategy generation, backtesting, and paper trading from natural language prompts, integrating with AI agents via an MCP server.24-
- AlicenseAqualityDmaintenanceAn MCP server that exposes trading analytics — technical indicators, portfolio state, risk metrics, and backtest results — as tools an LLM agent can call.5MIT
- AlicenseAqualityDmaintenanceAn MCP server that exposes futures prop firm data and personalized recommendation logic to AI agents like Claude and ChatGPT.6MIT
- FlicenseAqualityDmaintenanceMCP 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-