HPSILab Quant Finance MCP Server for Stock & Options Analytics

HPSILab is an open-source Python quantitative finance MCP server for research on US equities, ETFs, and supported options. It brings stock signals, implied volatility, options analytics, Monte Carlo simulation, AI prediction, backtesting, and risk analysis into ChatGPT, Claude, Cursor, VS Code, and other MCP clients. Connect once, ask in natural language, and receive structured results that an assistant can compare and explain.

Get a Free API Key · Pricing · Python SDK

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

Current package and server version: 0.9.2. An unpackaged source checkout identifies itself as 0.9.2+source so initialization metadata and outbound User-Agent values never fall back to 0.0.0.

Monte Carlo research example

Example visualization of scenario-based Monte Carlo research output. Results depend on the selected inputs and model assumptions. See get_monte_carlo for tool details.

Quick start: Official Remote MCP

The hosted Streamable HTTP service is recommended and requires no local installation. The following is a Claude Code .mcp.json example; other clients use different configuration schemas, documented below.

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

1. Register a free account, sign in, and generate an API key from Settings.
2. Replace hpsi_your_key in your client's private MCP configuration. Never commit or paste a real key into chat.
3. Connect the server and verify it with:

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

All financial research tools require a valid API key. See client setup and authentication for details.

If the key is missing, the package stops locally before constructing the downstream client or sending a request:

{
  "error": "api_key_required",
  "message": "A free API key is required.",
  "register_url": "https://hpsilab.com/register",
  "docs_url": "https://hpsilab.com/developer/v2"
}

401 and 402 responses are never retried. A 429 is retried only when it carries a valid Retry-After. Read-only calls use a finite retry budget for timeouts and recoverable 500/502/503/504 responses; artifact-producing calls are not automatically retried.

The local adapter also applies one safeguard per API key: 10 requests per rolling minute. Anonymous callers have zero tool requests. Each actual downstream attempt, including a retry, consumes one local allowance. This is burst protection, not a quota — entitlement is measured in Credits, and only the hosted API knows the balance and the plan.

A 429 means the caller is going too fast and nothing else, so it carries no registration or upgrade guidance; its next_actions holds the one action that resolves it, {"type": "retry_after", "seconds": n}. An empty Credit balance is a different response with a different remedy: HTTP 402 with error_code: "insufficient_credits", credits_required, credits_remaining, credits_charged: 0, and a next_actions list naming registration for a caller with no account or a Credits purchase for one who has an account. A payment whose outcome could not be confirmed is error_code: "settlement_unknown" with a call_id and an empty next_actions — do not retry it and do not pay for it again.

Quick start: Local stdio

For clients that require local stdio:

pip install -U hpsilab-quant-finance-mcp

Direct Python Usage

Create a .env file:

HPSILAB_API_KEY=hpsi_your_key

Then run:

import os
from dotenv import load_dotenv

load_dotenv()

HPSILAB_API_KEY = os.getenv("HPSILAB_API_KEY")

if not HPSILAB_API_KEY:
    raise RuntimeError("HPSILAB_API_KEY is not configured")

from hpsilab_quant_finance_mcp import server

result = server.get_ai_prediction("NVDA")
print(result)

For MCP, add the stdio server to the client's private configuration. This example uses the mcpServers schema supported by Claude and Cursor; VS Code and GitHub Copilot use a servers schema instead.

{
  "mcpServers": {
    "hpsilab": {
      "command": "hpsilab-quant-finance-mcp",
      "env": {
        "HPSILAB_API_KEY": "hpsi_your_key"
      }
    }
  }
}

Then verify it through the MCP client:

Use HPSILab to get the AI prediction for NVDA and summarize the model consensus.

The client discovers tools with MCP tools/list and invokes them with tools/call. See local setup and Python usage.

Why HPSILab

HPSILab gives assistants typed inputs, structured outputs, ticker validation, machine-readable errors, and dedicated tools instead of invented metrics. It supports US-listed equities, ETFs, and supported options data; coverage and limits depend on the hosted service and plan.

Tools

The public product surface contains 9 public financial research tools.

Research tools accept one exchange ticker such as NVDA, SPY, or BRK.B; company names are not accepted. Live results can change between calls. Artifact tools can consume quota and should not be retried automatically.

Full inputs, outputs, side effects, and tool-selection guidance are in docs/tools.md.

Copy-ready prompts

Claude

Use HPSILab to analyze NVDA. Summarize the directional signal, AI model
consensus, IV regime, options pressure, 30-day Monte Carlo range, and the
three most important risks. Distinguish tool data from interpretation.

Cursor

Use HPSILab's IV radar and option-pressure tools for SPY. Compare IV rank,
percentile, skew, expected move, max pain, gamma wall, and pressure zones.
Return a compact table and do not recommend a trade.

ChatGPT

Run the HPSILab pre-trade risk scan for TSLA. Explain every warning or failed
check, preserve unavailable fields as unavailable, and quote the returned
reason instead of guessing. Do not execute or recommend a trade.

Setup guidance covers ChatGPT, Claude, Cursor, VS Code, GitHub Copilot, Continue, and Kimi. See the client setup guide for each client's transport and configuration format.

Safety and license

HPSILab is for research and education only. Outputs may be incomplete, delayed, or wrong and are not investment, financial, or trading advice. The MCP server has no brokerage connectivity, order entry, or trade-execution capability.

Licensed under the MIT License. Contributions are welcome; read AGENTS.md and CONTRIBUTING.md before proposing public schema changes.