HPSILab Quant Finance MCP Server for Stock & Options Analytics

Stock and options risk analytics for AI agents. Connect one remote MCP endpoint, https://hpsilab.com/mcp, sign in with OAuth (no API key to paste), and your agent can call:

• a pre-trade risk scan: volatility, beta, drawdown and VaR against SPY with fixed pass/warn/fail limits, plus sizing, sector exposure and correlation checks;
• options structure: IV level, rank and skew, gamma wall, call/put walls, max pain;
• a 10-trading-day Monte Carlo price range and odds of finishing higher;
• analyze_stock for a one-call overview, plus AI prediction and backtests.

Results are structured JSON with machine-readable errors, for US-listed equities, ETFs and supported options. This repository is the open-source Python server (MIT); the hosted endpoint runs the same tool surface.

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

Get a Free API Key · Pricing · Tool reference · Client setup · Python SDK

Connect: hosted Streamable HTTP

Recommended, and requires no local installation.

With OAuth sign-in

Clients that support MCP OAuth (Claude Code, Claude.ai and ChatGPT connectors, and others) only need the URL; they open the HPSILab sign-in page on first use.

claude mcp add --transport http hpsilab https://hpsilab.com/mcp

In a connector UI, add a custom connector with the URL https://hpsilab.com/mcp.

With an API key

For clients without OAuth support, or for scripts:

1. Register a free account, sign in, and generate an API key from Settings.
2. Add the server to your client's private configuration, replacing hpsi_your_key. Never commit a real key or paste one into chat.

The example below is Claude Code's .mcp.json; other clients use different configuration schemas, all covered in client setup.

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

3. Verify the connection:

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 signed-in account: OAuth or a valid API key. See authentication for key handling and rotation.

Connect: local stdio

For clients that require a local process:

pip install -U hpsilab-quant-finance-mcp

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, which also covers calling the tool functions directly from Python.

Tools

Nine financial research tools, plus register_account. Tool names and parameter meanings are part of the public compatibility contract.

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.

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.

Copy-ready prompts

Claude

Use HPSILab to analyze NVDA. Summarize the directional signal, AI model
consensus, IV regime, options pressure, 10-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.

Errors, retries, and limits

Every failure is a structured object with a stable error_code, never prose an agent has to pattern-match. Five refusals matter, because each has a different remedy:

Without a key 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 retried automatically. The package also applies one process-local safeguard of 10 requests per rolling minute per API key — burst protection, not a quota, since only the hosted service knows the balance and the plan.

Field-by-field payloads, the Credits circuit breaker, and the reasoning behind each remedy are in docs/authentication.md and docs/python-sdk.md.

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.

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.