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.
-
Create an account at hpsilab.com and generate an API key in Settings.
-
Add this remote MCP server to your client:
-
Send the header Authorization: Bearer hpsi_your_key if the client supports custom headers.
-
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:
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:
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.
- Read AGENTS.md for the repository contract.
- Read CONTRIBUTING.md for setup, testing, and pull-request expectations.
- Open an issue before proposing a new tool or any public schema change.
- 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