hpsilab-quant-finance-mcp 0.5.2

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.

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

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

https://api.hpsilab.com/mcp

---

Quick Start

Step 1 — Get an API Key

Create an account at 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.

https://api.hpsilab.com/mcp

Option 2 — Open Source Self-Hosted MCP Server

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:

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 in Quick Start.

Installation

pip install hpsilab-mcp

Quick Start

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

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

{
  "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):

{
  "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:

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

Self-Hosted (Cursor)

{
  "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:

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

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

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

{
  "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:

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.

# 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:

{
  "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

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