hpsilab-quant-finance-mcp

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