hpsilab-quant-finance-mcp 0.5.4

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

Production-focused quantitative research for US stocks and options, available directly inside ChatGPT, Claude, VS Code, GitHub Copilot, Cursor, Continue, Kimi, and other MCP clients.

HPSILab combines stock signals, implied volatility, options positioning, Monte Carlo scenarios, strategy backtests, pre-trade risk checks, charts, and research reports behind nine purpose-built MCP tools. Ask a question in natural language and receive structured data that an assistant can explain, compare, and use in a larger research workflow.

Research and educational use only. HPSILab does not execute trades and does not provide investment advice.

Hosted endpoint: https://hpsilab.com/mcp

Analyze NVDA with HPSILab. Summarize the directional signal, IV regime,
options pressure, 30-day Monte Carlo range, and the three most important risks.

Quick start · Client guides · Prompt library · Tool reference

Screenshot placeholder — end-to-end stock analysis in an MCP client

Why this server exists

General-purpose assistants can explain finance, but they should not invent live metrics or silently mix data from incompatible sources. HPSILab provides a narrow, explicit tool contract for quantitative research:

• structured outputs instead of prose that must be scraped;
• specialized tools for volatility, options positioning, probability, backtests, and risk;
• consistent ticker validation and machine-readable errors;
• clear read-only and side-effect annotations for MCP clients;
• the same research surface through hosted Streamable HTTP and local stdio transports.

The project is designed for investors, options researchers, quantitative developers, financial research teams, and agent builders who need evidence-rich analysis—not automated trading.

Features

• Unified stock analysis — combine multiple quantitative signals into a bull, bear, or neutral view.
• AI prediction — inspect next-session direction, probability, confidence, regime, and model consensus.
• Implied-volatility radar — evaluate ATM IV, IV rank, percentile, skew, and volatility regime.
• Options pressure — identify max pain, gamma walls, expected moves, squeeze targets, and strike concentrations.
• Monte Carlo simulation — explore 30-day price distributions and downside probabilities.
• Strategy backtests — compare returns, Sharpe and Sortino ratios, drawdown, and win rate.
• Pre-trade risk scan — review volatility, beta, VaR, drawdown, sizing, exposure, and correlation checks.
• Research artifacts — generate structured reports and hosted chart images.
• Agent-friendly contract — typed inputs, structured dictionaries, stable tool names, and explicit MCP annotations.

Quick Start

The hosted Streamable HTTP endpoint is the recommended path. It requires no local Python installation and always exposes the current server version.

1. Create an account at hpsilab.com and generate an API key in Settings.

2. Add this remote MCP server to your client:

   https://hpsilab.com/mcp
   

3. Send the header Authorization: Bearer hpsi_your_key if the client supports custom headers.

4. Ask:

   Use HPSILab to analyze AAPL. Separate observed metrics from interpretation,
   identify conflicting signals, and finish with a concise risk summary.
   

The hosted service may expose rate-limited anonymous tools without a key. Authenticated access is recommended for predictable quotas and the complete account-enabled experience.

Installation

Option A: hosted MCP service (recommended)

Configure your client with the endpoint and bearer header shown above. See the client-specific guides below for exact steps.

Option B: local stdio server

The local package delegates calculations to the HPSILab API through the hpsilab-mcp SDK, so it still requires network access and a valid API key.

pip install hpsilab-quant-finance-mcp

macOS or Linux:

export HPSILAB_API_KEY=hpsi_your_key
hpsilab-quant-finance-mcp

Windows PowerShell:

$env:HPSILAB_API_KEY = "hpsi_your_key"
hpsilab-quant-finance-mcp

For clients that support uvx, use:

command: uvx
args: hpsilab-quant-finance-mcp
environment: HPSILAB_API_KEY=hpsi_your_key

Option C: install from source

git clone https://github.com/haiyunsky/hpsilab-quant-finance-mcp.git
cd hpsilab-quant-finance-mcp
python -m venv .venv
python -m pip install -e .

Set HPSILAB_API_KEY, then run hpsilab-quant-finance-mcp.

Local Streamable HTTP

The same nine tools can be served locally over the standard HTTP transport without duplicating business logic:

hpsilab-quant-finance-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Connect a client to http://127.0.0.1:8000/mcp. This development mode uses the process-level HPSILAB_API_KEY; keep it bound to loopback unless you have configured production TLS, authentication, allowed hosts/origins, and trusted proxy behavior.

Python REST SDK

Applications that need direct Python/REST access rather than MCP should use the separate hpsilab-mcp package. The REST SDK and this MCP server are related products, but they are not interchangeable transports.

Supported MCP clients

Client	Hosted HTTP	Local stdio	Guide
ChatGPT	Yes	No	ChatGPT setup
Claude / Claude Code / Claude Desktop	Yes	Yes	Claude setup
VS Code	Yes	Yes	VS Code setup
GitHub Copilot	Yes	Yes	Copilot setup
Cursor	Yes	Yes	Cursor setup
Continue	Yes	Yes	Use the client's MCP configuration UI with the endpoint above
Kimi Code	Yes	Yes	Use Streamable HTTP or uvx with the settings above

MCP capabilities and configuration formats evolve. Use the linked guides and your client's current documentation if a UI label has changed.

Example prompts

Fast stock research

Use HPSILab to analyze MSFT. Give me the overall signal, confidence, strongest
bullish and bearish evidence, and any disagreement between the underlying models.

Options and volatility

Use HPSILab to evaluate TSLA options. Compare IV rank and percentile with the
expected move, max pain, gamma wall, and pressure zones. Do not recommend a trade.

Risk-first workflow

Run the HPSILab pre-trade risk scan for NVDA. Explain every warning or failed
check, show how portfolio exposure changes, and state when data is unavailable.

More copy-ready workflows:

• Stock analysis
• Options and volatility
• Earnings research
• Portfolio research
• Risk scans

Screenshots

The following placeholders identify the product views that should be captured before the next documentation release. Screenshots must use non-sensitive demo data and must not expose an API key or account information.

Placeholder 1 — multi-signal stock analysis response

Placeholder 2 — implied volatility and options positioning

Placeholder 3 — risk scan and portfolio impact

Architecture

flowchart LR
    C["MCP client<br/>ChatGPT · Claude · VS Code · Cursor · Continue · Kimi"]
    R["Hosted Streamable HTTP<br/>https://hpsilab.com/mcp"]
    S["Local stdio server<br/>hpsilab-quant-finance-mcp"]
    SDK["hpsilab-mcp Python SDK"]
    API["HPSILab quantitative API"]
    Q["Market data · IV engine · models<br/>simulation · backtests · risk"]

    C --> R
    C --> S
    S --> SDK
    R --> API
    SDK --> API
    API --> Q

This repository owns the MCP interface and its stdio/Streamable HTTP adapters. The hpsilab-mcp SDK owns hosted REST paths and downstream API transport behavior used by the shared service layer.

Detailed engineering references:

• Architecture and authentication boundaries
• MCP protocol compatibility review
• Phase 2 migration notes

Tools

Tool names are part of the public compatibility contract and are not renamed casually.

Tool	Purpose	Side-effect profile
analyze_stock	Aggregate directional and quantitative stock analysis	Read-only, idempotent
get_ai_prediction	Next-session model prediction and consensus	Read-only, idempotent
get_iv_radar	IV level, rank, percentile, skew, and regime	Read-only, idempotent
get_option_pressure	Max pain, gamma walls, expected move, and pressure zones	Read-only, idempotent
get_monte_carlo	Thirty-day simulated price distribution and probabilities	Read-only, idempotent
get_equity_curves	Strategy backtests and risk-adjusted performance	Read-only, idempotent
get_pretrade_risk_scan	Position, portfolio exposure, and correlation risk checks	Read-only, idempotent
generate_stock_images	Create hosted chart artifacts	Creates artifacts; not idempotent
generate_stock_research_report	Create a structured hosted research report	Creates an artifact; not idempotent

All tools accept an exchange ticker such as NVDA, AAPL, SPY, or BRK.B. Company names are not accepted in place of tickers. Live outputs can change between calls. Artifact-producing tools may consume quota, and generated image URLs can expire.

FAQ

Is HPSILab a trading bot?

No. It provides quantitative research data and analysis tools. It does not place, route, or manage orders.

Do I need an API key?

The local stdio package requires HPSILAB_API_KEY. The hosted endpoint may allow a rate-limited anonymous subset, but authenticated access is recommended and may be required for account-dependent tools.

What markets are supported?

The current tool surface is designed for US-listed equities, ETFs, and their supported options data. Coverage is governed by the hosted service and account tier.

Why did the server reject a company name?

Tools require an exchange ticker. Use NVDA, not NVIDIA; use BRK.B where the exchange ticker includes a class suffix.

Why are exposure or correlation fields empty?

Those sections depend on an existing tracked watchlist or portfolio. When unavailable, the response includes available: false and a reason; clients should surface that reason instead of guessing.

Why did a chart or report call run twice?

Artifact-producing tools are deliberately marked non-idempotent. Repeating a call can create another artifact or consume quota. Review client approval prompts before retrying.

How do I troubleshoot a connection?

Confirm the endpoint is exactly https://hpsilab.com/mcp, verify the bearer header or HPSILAB_API_KEY, restart the MCP server after configuration changes, and inspect your client's MCP logs. Client-specific checks are in the linked setup guides.

Is the output investment advice?

No. Outputs are for research and education and can be incomplete, delayed, or wrong. Independently verify material facts and consult a qualified professional where appropriate.

Contributing

Contributions that improve reliability, interoperability, tests, documentation, and developer experience are welcome.

1. Read AGENTS.md for the repository contract.
2. Read CONTRIBUTING.md for setup, testing, and pull-request expectations.
3. Open an issue before proposing a new tool or any public schema change.
4. Keep changes backward compatible and include tests for observable behavior changes.

Please report vulnerabilities privately according to SECURITY.md, and follow the Code of Conduct.

License

MIT © 2026 Haiyun Hu