Metadata-Version: 2.4
Name: hpsilab-quant-finance-mcp
Version: 0.5.2
Summary: Quant finance MCP server for stock analysis, options analytics, implied volatility, Monte Carlo simulation, AI prediction, pre-trade risk scanning, research reports, chart generation, and backtesting.
Author: Haiyun Hu
License: MIT
Project-URL: Homepage, https://hpsilab.com
Project-URL: Repository, https://github.com/haiyunsky/hpsilab-quant-finance-mcp
Project-URL: MCP Directory, https://glama.ai/mcp/servers/haiyunsky/hpsilab-quant-finance-mcp
Project-URL: Python REST SDK, https://pypi.org/project/hpsilab-mcp/
Keywords: mcp,mcp-server,model-context-protocol,quantitative-finance,financial-research,stock-analysis,options-analytics,implied-volatility,monte-carlo,backtesting,ai-agent,claude-mcp,cursor-mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hpsilab-mcp>=0.5.2
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# HPSILab - Quant Finance MCP Server for Stock Analysis and Options Analytics

<!-- mcp-name: io.github.haiyunsky/hpsilab-quant-finance-mcp -->

[![Website](https://img.shields.io/badge/HPSILab-hpsilab.com-orange)](https://hpsilab.com)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![PyPI](https://img.shields.io/pypi/v/hpsilab-quant-finance-mcp?label=PyPI)](https://pypi.org/project/hpsilab-quant-finance-mcp/)
[![PyPI SDK](https://img.shields.io/pypi/v/hpsilab-mcp?label=PyPI%20SDK)](https://pypi.org/project/hpsilab-mcp/)
[![Glama](https://glama.ai/mcp/servers/haiyunsky/hpsilab-quant-finance-mcp/badge)](https://glama.ai/mcp/servers/haiyunsky/hpsilab-quant-finance-mcp)
[![Smithery](https://smithery.ai/badge/g-scorpiosky/hpsilab-quantum-finance)](https://smithery.ai/servers/g-scorpiosky/hpsilab-quantum-finance)

If this quant finance MCP server is useful, please star the repository.

**9-tool Model Context Protocol server for quantitative finance, stock analysis, options analytics, implied volatility radar, Monte Carlo stock simulation, AI prediction signals, pre-trade risk scanning, research reports, chart visualization, and backtesting.**

Use HPSILab with Claude, Cursor, ChatGPT Agents, Cline, Windsurf, and other MCP-compatible clients to research US equities and options workflows from a single API-backed toolset.

Best fit: active investors, options researchers, quant developers, financial research teams, and AI agent builders who need market data analysis tools rather than generic chat output.

**Official Remote MCP Endpoint**

```text
https://api.hpsilab.com/mcp
```

---

## Quick Start

### Step 1 — Get an API Key

Create an account at [hpsilab.com](https://hpsilab.com) and generate an API key (`hpsi_...`) from the settings.

### Step 2 — Which option should I use?

| Option | Setup Time | Best For |
| --- | --- | --- |
| Remote MCP (`https://api.hpsilab.com/mcp`) | Instant | Most users |
| Python REST SDK (`pip install hpsilab-mcp`) | Instant | Python developers |
| Self-Hosted MCP Server | 2–3 minutes | Self-hosted setups |
| Enterprise Deployment | Custom | Organizations |

### Option 1 — Official Remote MCP Service (Recommended)

Connect directly to the official HPSILab MCP endpoint — no installation required, always up to date.

```text
https://api.hpsilab.com/mcp
```

### Option 2 — Open Source Self-Hosted MCP Server

```bash
pip install hpsilab-quant-finance-mcp
export HPSILAB_API_KEY=hpsi_your_key   # Windows: set HPSILAB_API_KEY=hpsi_your_key
hpsilab-quant-finance-mcp
```

Published on PyPI: https://pypi.org/project/hpsilab-quant-finance-mcp/

To modify the source instead of installing the release, clone and install in editable mode:

```bash
git clone https://github.com/haiyunsky/hpsilab-quant-finance-mcp.git
cd hpsilab-quant-finance-mcp
pip install -e .
cp env.example .env
# edit .env and set HPSILAB_API_KEY=hpsi_your_key
hpsilab-quant-finance-mcp
```

---

## Full Feature Access

The HPSILab MCP server exposes all 9 tools through both the official remote endpoint and the open source self-hosted server. No MCP tool is hidden behind a local feature flag in this repository.

| Tool | Remote MCP | Self-hosted MCP | Python REST SDK |
| --- | --- | --- | --- |
| `analyze_stock` | Available | Available | Available |
| `get_ai_prediction` | Available | Available | Available |
| `get_iv_radar` | Available | Available | Available |
| `get_option_pressure` | Available | Available | Available |
| `get_monte_carlo` | Available | Available | Available |
| `get_equity_curves` | Available | Available | Available |
| `get_pretrade_risk_scan` | Available | Available | Available |
| `generate_stock_images` | Available | Available | Available |
| `generate_stock_research_report` | Available | Available | Available |

All calls still require a valid HPSILab API key. The hosted API may enforce account-level usage quotas, rate limits, and symbol coverage, but the MCP server registers the complete tool surface.

---

## Python REST SDK

If you prefer direct REST access without MCP transport, use the official Python SDK package `hpsilab-mcp`. You'll need an API key — see [Step 1](#step-1--get-an-api-key) in Quick Start.

### Installation

```bash
pip install hpsilab-mcp
```

### Quick Start

```python
from hpsilab_mcp import HpsiMcpClient

client = HpsiMcpClient(
    api_key="hpsi_your_key",
    base_url="https://hpsilab.com",
)

# Run all tools in one go
result = client.analyze_stock("NVDA")
print(result)
```

### Available SDK Methods

```python
client.analyze_stock("NVDA")
client.get_ai_prediction("NVDA")
client.get_iv_radar("NVDA")
client.get_option_pressure("NVDA")
client.get_monte_carlo("NVDA")
client.get_pretrade_risk_scan("NVDA")
client.get_equity_curves("NVDA")
client.generate_stock_images("NVDA")
client.generate_stock_research_report("NVDA")
```

### REST Endpoint Mapping

The MCP server does not call these endpoints directly — it delegates every
call to the `hpsilab-mcp` SDK's `HpsiMcpClient`, which is the single source
of truth for paths/methods. This table documents what the SDK currently
calls; if it and [Available SDK Methods](#available-sdk-methods) above ever
disagree, trust the SDK's source.

| Method | Endpoint |
| --- | --- |
| `analyze_stock(symbol)` | `GET /api/analyze_stock/{symbol}` |
| `get_ai_prediction(symbol)` | `GET /api/ai_prediction/{symbol}` |
| `get_iv_radar(symbol)` | `GET /api/iv_batch?symbols={symbol}` |
| `get_option_pressure(symbol)` | `GET /api/option_pressure/{symbol}` |
| `get_monte_carlo(symbol)` | `GET /api/monte_carlo/{symbol}` |
| `get_equity_curves(symbol)` | `GET /api/equity_curve/{symbol}` |
| `get_pretrade_risk_scan(symbol)` | `GET /api/pretrade-risk-scan?symbol={symbol}` |
| `generate_stock_images(symbol)` | `POST /api/stock_report/{symbol}/images` |
| `generate_stock_research_report(symbol)` | `POST /api/stock_report/{symbol}/research_report` |

### Capability Matrix

| Capability | REST SDK | MCP |
| --- | --- | --- |
| `analyze_stock` | ✅ | ✅ |
| `get_ai_prediction` | ✅ | ✅ |
| `get_iv_radar` | ✅ | ✅ |
| `get_option_pressure` | ✅ | ✅ |
| `get_monte_carlo` | ✅ | ✅ |
| `get_equity_curves` | ✅ | ✅ |
| `get_pretrade_risk_scan` | ✅ | ✅ |
| `generate_stock_images` | ✅ | ✅ |
| `generate_stock_research_report` | ✅ | ✅ |

> **Note:** The Python SDK wraps the hosted REST API and does not implement MCP transport, SSE, streaming, or tool discovery. Use an MCP client when you need assistant-native tool calls or tool discovery.

---

## MCP Client Configuration

### Cursor (Remote MCP)

```json
{
  "mcpServers": {
    "hpsilab": {
      "url": "https://api.hpsilab.com/mcp",
      "headers": {
        "Authorization": "Bearer hpsi_your_key"
      }
    }
  }
}
```

### Claude Code (CLI or VS Code extension)

Claude Code speaks Streamable HTTP natively — no proxy needed. Either run
`claude mcp add` and follow its prompts (transport `http`, URL below), or add
this block directly to your Claude config (global `~/.claude.json`, or a
project-local `.mcp.json` if you want it scoped to one repo instead of every
project):

```json
{
  "mcpServers": {
    "hpsilab": {
      "type": "http",
      "url": "https://api.hpsilab.com/mcp",
      "headers": { "Authorization": "Bearer hpsi_your_key" }
    }
  }
}
```

The `headers` field is optional — free-tier tools work anonymously without
an API key (rate-limited, demo mode).

### Claude Desktop (via mcp-remote)

Claude Desktop needs the `mcp-remote` bridge for a remote HTTP server with
custom headers:

```json
{
  "mcpServers": {
    "hpsilab": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.hpsilab.com/mcp",
        "--header",
        "Authorization: Bearer hpsi_your_key"
      ]
    }
  }
}
```

### Self-Hosted (Cursor)

```json
{
  "mcpServers": {
    "hpsilab": {
      "command": "hpsilab-quant-finance-mcp"
    }
  }
}
```

### VS Code (GitHub Copilot Chat)

Requires the GitHub Copilot Chat extension. Once added, switch Copilot Chat
to **Agent** mode — the 9 tools appear there.

**One command** (documented VS Code CLI flag — adds to your user profile).

macOS / Linux / Git Bash:

```bash
code --add-mcp "{\"name\":\"hpsilab\",\"type\":\"http\",\"url\":\"https://api.hpsilab.com/mcp\"}"
```

Windows PowerShell (quotes must be escaped as `\"` inside single quotes):

```powershell
code --add-mcp '{\"name\":\"hpsilab\",\"type\":\"http\",\"url\":\"https://api.hpsilab.com/mcp\"}'
```

**Or browse for it in-editor**: Extensions view (`Ctrl+Shift+X`) → search
`@mcp` → look for `hpsilab`. (Whether it appears there depends on gallery
indexing outside our control — if it's not listed yet, use the command
above or the manual config below, both work regardless.)

**Or configure manually** — add to `.vscode/mcp.json` (workspace) or your
user `mcp.json` (Command Palette → **MCP: Open User Configuration**):

```json
{
  "servers": {
    "hpsilab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["hpsilab-quant-finance-mcp"],
      "env": { "HPSILAB_API_KEY": "${input:hpsilab_api_key}" }
    }
  },
  "inputs": [
    { "id": "hpsilab_api_key", "type": "promptString", "description": "HPSILab API key", "password": true }
  ]
}
```

---

## Available Tools

All tools accept a single `symbol` parameter: an exchange ticker in uppercase (e.g. `"NVDA"`, `"AAPL"`, `"SPY"`).

### `analyze_stock`

Full institutional-grade analysis — aggregates AI prediction, IV radar, options pressure, Monte Carlo, and backtesting into a single bull/bear verdict.

**Use when:** you need a holistic market view with confidence score and supporting evidence.

**Returns:** `signal`, `confidence_score`, `bullish_factors`, `bearish_factors`, `summary`

---

### `get_iv_radar`

Implied volatility metrics: ATM IV, IV rank (0–100), IV percentile, risk reversal direction, and volatility regime.

**Use when:** you want to assess whether options are cheap or expensive, or identify the current vol regime.

**Returns:** `atm_iv`, `iv_rank`, `iv_percentile`, `risk_reversal`, `volatility_regime`

---

### `get_option_pressure`

Options-market positioning and dealer-hedging pressure zones: max pain, gamma wall, expected move, and squeeze targets.

**Use when:** you need strike-level gravitational targets near expiration or want to size an expected-move trade.

**Returns:** `max_pain`, `gamma_wall`, `expected_move`, `squeeze_target`, `expiry_date`, `pressure_zones`

---

### `get_monte_carlo`

10,000-path GBM Monte Carlo simulation over a 30-day horizon, calibrated with realized volatility and current IV.

**Use when:** you need a probabilistic price range, downside probability estimates, or volatility-adjusted scenarios.

**Returns:** `mean_price`, `range_90`, `range_68`, `prob_above_spot`, `prob_10pct_drop`, `distribution`

---

### `get_ai_prediction`

Ensemble AI directional prediction (gradient-boosted trees + LSTM + quantum VQC) for the next session's move.

**Use when:** you want a data-driven up/down probability with per-model votes and market regime classification.

**Returns:** `prediction`, `up_probability`, `confidence`, `model_votes`, `regime`, `signal_strength`

---

### `get_equity_curves`

Backtested equity curves and risk-adjusted metrics (Sharpe, Sortino, max drawdown, win rate) for standard quant strategies applied to the ticker.

**Use when:** you want historical performance context or need to compare strategy quality across tickers.

**Returns:** `strategies[]` — each with `total_return`, `sharpe_ratio`, `max_drawdown`, `win_rate`, `equity_curve`

---

### `get_pretrade_risk_scan`

Pre-trade risk scan for a single stock, returned as the full API JSON response without modification.

**Parameters:** `symbol` (required) - exchange ticker, e.g. `"NVDA"`, `"AAPL"`, `"SPY"`.

**Example:**

```python
get_pretrade_risk_scan("NVDA")
```

**Returns:** full JSON response from `GET /api/pretrade-risk-scan?symbol={symbol}`

**Pricing status:** signed-in users call this tool free of charge. Anonymous calls are planned to require an x402 micropayment (draft reference: $0.15 USDC) once self-hosted x402 middleware validation on Base Sepolia testnet is complete. Not yet listed on MCPize pricing pending resolution of a metadata gap.

---

### `generate_stock_research_report`

Generates a structured markdown research note synthesizing all signal sources, suitable for sharing with investors.

**Use when:** a user asks for a "report" or "write-up" and needs a formatted narrative rather than raw JSON.

**Returns:** `report` (markdown string), `generated_at`

**Pricing status:** signed-in users call this tool free of charge. Anonymous calls are planned to require an x402 micropayment (draft reference: $0.35 USDC) once self-hosted x402 middleware validation on Base Sepolia testnet is complete.

---

### `generate_stock_images`

Returns public URLs for three charts: candlestick price chart, 3-D IV surface, and options flow heatmap. URLs expire after 24 hours.

**Use when:** a user asks to "see" or "visualize" a chart, or you want to embed visuals in a report.

**Returns:** `price_chart_url`, `iv_surface_url`, `options_flow_url`, `expires_at`

---

## Example

More copy-paste prompts are available in [examples/prompts.md](examples/prompts.md).

```python
# Quick directional verdict
analyze_stock("NVDA")

# Only need vol data
get_iv_radar("NVDA")

# Probabilistic price range
get_monte_carlo("NVDA")

# Pre-trade risk scan
get_pretrade_risk_scan("NVDA")
```

**Example `analyze_stock` response:**

```json
{
  "symbol": "NVDA",
  "signal": "Bearish",
  "confidence_score": 42,
  "bullish_factors": [
    "Monte Carlo range midpoint is above current spot.",
    "Option pressure leaves a meaningful upside weekly-high zone."
  ],
  "bearish_factors": [
    "AI prediction gives only a 34.2% probability of an up close.",
    "Max Pain sits below spot, suggesting downward expiry pin pressure.",
    "Risk reversal is put-heavy.",
    "All three AI models point down."
  ],
  "summary": "NVDA screens bearish with a 42/100 direction score."
}
```

---

## Architecture

```text
AI Client (Claude / Cursor / Windsurf / ...)
    ↓  MCP protocol
hpsilab-quant-finance-mcp  (this repo)
    ↓  HTTPS REST
HPSILab Quant API  (hpsilab.com)
    ↓
Quant Platform  (IV engine · ML models · Monte Carlo · Backtester)

Python App / Script
    ↓  hpsilab-mcp (pip package)
HPSILab Quant API  (hpsilab.com)
    ↓
Quant Platform  (IV engine · ML models · Monte Carlo · Backtester)
```

---

## Supported MCP Clients

Cursor · Claude Desktop · Claude Code · ChatGPT Agents · Cline · Roo Code · Windsurf · Continue · Any MCP-compatible client

---

## Pricing & Access Tiers

All 9 tools are reachable through the endpoints above. Access currently works as follows:

| Tier | Tools | Requirement |
| --- | --- | --- |
| Free (anonymous) | `analyze_stock`, `get_iv_radar`, `get_option_pressure`, `get_monte_carlo`, `get_ai_prediction`, `get_equity_curves` | None |
| Pro (signed-in) | `generate_stock_research_report`, `get_pretrade_risk_scan` | API key |

**In progress:** an x402 (HTTP micropayment) tier is under validation on Base Sepolia testnet. Once live, anonymous (non-signed-in) calls to `get_pretrade_risk_scan` and `generate_stock_research_report` will require a per-call USDC micropayment; signed-in access to these tools remains free. Draft reference pricing: `get_pretrade_risk_scan` $0.15, `generate_stock_research_report` $0.35 — subject to change pending testnet results. No other tools are in scope for this change at this time.

---

## Who Pays for This

This server is built for users who already have a recurring research workflow:

- Options traders who repeatedly check IV rank, skew, expected move, gamma walls, max pain, and squeeze targets.
- Quant developers who want MCP-native access to Monte Carlo simulations, AI prediction signals, and equity curve backtests.
- Financial advisors, research writers, and market analysts who need repeatable stock research reports and charts.
- AI agent builders who need stock analysis tools for Claude, Cursor, ChatGPT Agents, Cline, Windsurf, or custom MCP clients.

The strongest paid use case is not generic stock chat. It is saving time on repeat options and quant research tasks that a user already performs every week.

---

## Search Keywords

Quant finance MCP server, stock analysis MCP server, options analytics MCP server, implied volatility MCP server, Monte Carlo stock simulation MCP, AI stock prediction MCP, backtesting MCP server, pre-trade risk MCP server, stock research report MCP, stock chart generation MCP, Claude stock analysis MCP, Cursor finance MCP server, ChatGPT stock analysis MCP, financial research MCP tools, Model Context Protocol finance tools, risk management, portfolio risk, portfolio allocation, exposure analysis, position sizing, implied volatility.

---

## Disclaimer

This software is provided for research and educational purposes only. Nothing contained in this project constitutes investment advice, financial advice, or a recommendation to buy or sell any security. Always perform your own due diligence before making investment decisions.

---

## License

MIT License — Copyright (c) 2026 Haiyun Hu
