Content
# 📈 Quant Research Assistant — MCP Server & Claude Plugin
> 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](https://imrohaninamdar.com) · [GitHub](https://github.com/irohan0)
---
## 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
```bash
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
```bash
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](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`:
```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
```bash
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
```bash
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
