Quant Research Assistant

A one-stop quantitative-finance toolkit that gives Claude live financial reasoning — price & risk analysis, strategy backtesting, HMM market-regime detection, options greeks, fundamentals & DCF valuation, news sentiment, regime-aware Monte Carlo, pairs trading, Fama-French factor attribution, portfolio optimisation, and a single composite quant score. Every data source is free — no API keys.

Built by Rohan Inamdar · imrohaninamdar.com · GitHub

---

What makes this different

Most quant tools give you a notebook or a dashboard. This gives Claude live financial reasoning: you talk to it in plain English, it calls production-grade financial tools under the hood, returns charts and structured data, and narrates the results.

Two standout, non-library features:

• HMM Market Regime Detection — an unsupervised Gaussian Hidden Markov Model trained on return, realised-volatility, momentum and z-score features that classifies market states (Bull / Bear / High-Volatility / Sideways) in real time.
• Regime-aware Monte Carlo — forward price simulation that switches between calm and stressed regimes using the HMM's transition matrix, so the downside tail looks like real markets instead of a tidy bell curve.

---

Tools (20)

Analysis

Tool	What it does
price_history	OHLCV fetch with candlestick + Bollinger + volume chart
risk_metrics	Sharpe, Sortino, Calmar, VaR, CVaR, beta, Jensen's alpha, skew, kurtosis
backtest	Vectorised SMA / RSI / Momentum / MACD vs buy-and-hold
market_regime	Gaussian HMM regime classification + transition matrix + posteriors
portfolio_optimisation	Max-Sharpe, Min-Vol, Risk-Parity + efficient frontier + correlation heatmap
macro_overlay	FRED macro indicators (rates, CPI YoY, VIX, yield curve) + rolling correlation
options_analytics	IV skew, put/call ratio, max pain, IV term structure, in-house Black-Scholes greeks
fundamentals	Ratios + two-stage DCF / reverse-DCF + Piotroski F-Score + Altman Z-Score
sentiment	Multi-source news headline sentiment (VADER over yfinance + Yahoo/Google RSS)
monte_carlo	Regime-aware / GBM / bootstrap forward simulation, fan chart, hit-probability, projected VaR
technicals	RSI, MACD, Bollinger, ADX, Stochastic, ATR, OBV, S/R, patterns → composite signal
pairs	Engle-Granger + ADF cointegration, hedge ratio, half-life, z-score backtest
factors	Fama-French 3-factor + momentum regression (betas, alpha, R², contributions)
composite_score	One 0–100 score + Strong-Buy→Strong-Sell verdict blending all lenses

Persistent state

add_to_watchlist · remove_from_watchlist · show_watchlist · save_portfolio_tool · load_portfolio_tool · list_portfolios_tool

Slash command

/quant-deep-dive <TICKER> — chains the tools into one narrated deep-dive report.

---

Architecture

Claude (MCP client)
        │  MCP protocol
        ▼
┌──────────────────────────────────────────────────────────┐
│  MCP Server (Python / FastMCP) — 20 tools                │
│  prices · metrics · backtest · regime · portfolio · macro │
│  options · fundamentals · sentiment · montecarlo          │
│  technicals · pairs · factors · score · watchlist         │
│  Shared compute: pandas · numpy · scipy · hmmlearn ·      │
│                  scikit-learn · statsmodels               │
└──────────────────────────────────────────────────────────┘
        │
        ▼  data sources (all free, no keys)
┌────────┐ ┌──────────┐ ┌────────────────┐ ┌───────────────┐ ┌────────────┐
│yfinance│ │ FRED CSV │ │ Ken French Lib │ │ Yahoo/Google  │ │SQLite cache│
│(prices,│ │ (macro)  │ │ (FF factors)   │ │ RSS (news)    │ │+watchlist  │
│options,│ └──────────┘ └────────────────┘ └───────────────┘ └────────────┘
│fund.)  │
└────────┘

---

Quick start

1. Install

git clone https://github.com/irohan0/quant-mcp.git
cd quant-mcp
python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Run the MCP server

python server.py

3a. Use as a Claude Code plugin (recommended: clone + local marketplace)

The tools run a local Python process, so the machine needs the dependencies. The reliable install is to clone, build the .venv (step 1 above), then add the local checkout as a marketplace:

/plugin marketplace add /path/to/quant-mcp     # CLAUDE_PLUGIN_ROOT → your checkout (has .venv)
/plugin install quant-research-assistant

The 20 tools and the /quant-deep-dive command then appear in your session. Verify with claude mcp list → look for plugin:quant-research-assistant … √ Connected.

Why local (not a bare GitHub-marketplace install): the plugin's MCP config (mcp-config.json) launches ${CLAUDE_PLUGIN_ROOT}/.venv/Scripts/python.exe. A local-path install points CLAUDE_PLUGIN_ROOT at your checkout, where the .venv lives. A pure marketplace add <github-url> clones the repo without the (git-ignored) .venv, so the server has no interpreter. If you install from GitHub, create a .venv + pip install inside the plugin's cache dir, or edit its mcp-config.json to point at a Python that has the deps. On macOS/Linux change the path to ${CLAUDE_PLUGIN_ROOT}/.venv/bin/python.

3b. Use with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "quant-research-assistant": {
      "command": "/path/to/quant-mcp/.venv/bin/python",
      "args": ["/path/to/quant-mcp/server.py"]
    }
  }
}

4. (Optional) Gradio web UI for demos

python web/app.py      # http://localhost:7860 — a tab per tool

---

Example prompts

"Give me the quant score for NVDA and explain the breakdown"

"/quant-deep-dive AAPL"

"Run a regime-aware Monte Carlo on TSLA for the next quarter — what's the
 probability it reaches $400, and what's the projected downside?"

"Show me AAPL's options: IV skew, put/call positioning, max pain and ATM greeks"

"Is KO–PEP cointegrated, and what does the pairs backtest look like?"

"What are SPY's Fama-French factor exposures and alpha over 3 years?"

"Build a max-Sharpe portfolio from AAPL, MSFT, GOOGL, SPY, BND, GLD and save it as 'core'"

---

Running tests

pytest tests/ -v       # 51 unit tests, fully network-free (synthetic data + mocks)

---

Tech stack

• MCP: mcp[cli] (FastMCP)
• Data (all free): yfinance (prices, options, fundamentals), FRED CSV, Ken French Data Library, Yahoo/Google Finance RSS
• Compute: pandas, numpy, scipy, statsmodels
• ML: hmmlearn (Gaussian HMM), scikit-learn
• Sentiment: vaderSentiment, feedparser
• Charts: matplotlib (dark theme, base64 PNG)
• Web UI: gradio
• Cache & state: sqlite3 (price cache + watchlist/portfolios)

---

Project structure

quant-mcp/
├── server.py                  ← MCP server (registers all 20 tools)
├── mcp-config.json            ← MCP server config (referenced by the plugin)
├── .claude-plugin/
│   ├── plugin.json            ← Claude Code plugin manifest
│   └── marketplace.json       ← single-plugin marketplace
├── commands/
│   └── quant-deep-dive.md     ← /quant-deep-dive slash command
├── tools/
│   ├── utils.py               ← caching, fetch, FRED, chart helpers
│   ├── prices.py  metrics.py  backtest.py  regime.py  portfolio.py  macro.py
│   ├── options.py  fundamentals.py  sentiment.py  montecarlo.py
│   ├── technicals.py  pairs.py  factors.py  score.py  watchlist.py
├── web/app.py                 ← Gradio web UI (tab per tool)
├── tests/test_tools.py        ← 51 network-free unit tests
└── pyproject.toml

---

Notes

• All data sources are free — no API keys required.
• Charts are base64-encoded PNGs in the chart_png_b64 field — render them for the user.
• SQLite cache avoids redundant fetches (12h TTL for prices, 24h for fundamentals/factors).
• yfinance and RSS are scrapers; tools degrade gracefully when a source is unavailable.
• Educational only — past performance does not guarantee future results.

License

MIT © Rohan Inamdar