{
  "markdown": "# HPSILab Quant Finance MCP Server for Stock & Options Analytics\n\n<!-- mcp-name: io.github.haiyunsky/hpsilab-quant-finance-mcp -->\n\n[![PyPI](https://img.shields.io/pypi/v/hpsilab-quant-finance-mcp?label=PyPI)](https://pypi.org/project/hpsilab-quant-finance-mcp/)\n[![CI](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/LICENSE)\n\nHPSILab is an open-source Python quantitative finance MCP server for research on\nUS equities, ETFs, and supported options. It brings stock signals, implied\nvolatility, options analytics, Monte Carlo simulation, AI prediction,\nbacktesting, and risk analysis into ChatGPT, Claude, Cursor, VS Code, and other\nMCP clients. Connect once, ask in natural language, and receive structured\nresults that an assistant can compare and explain.\n\n> Research and educational use only. HPSILab does not provide investment advice\n> and does not execute trades.\n\n[Get a Free API Key](https://hpsilab.com/register) · [Pricing](https://hpsilab.com/pricing) · [Tool reference](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/tools.md) · [Client setup](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/client-setup.md) · [Python SDK](https://pypi.org/project/hpsilab-mcp/)\n\n| | |\n| --- | --- |\n| **Registry name** | `io.github.haiyunsky/hpsilab-quant-finance-mcp` |\n| **Version** | 0.10.0 — a source checkout reports `0.10.0+source` |\n| **Transports** | Streamable HTTP (hosted) · stdio (PyPI package) |\n| **Remote endpoint** | `https://hpsilab.com/mcp` |\n| **Package** | `pip install -U hpsilab-quant-finance-mcp` |\n| **Authentication** | Bearer API key, or `HPSILAB_API_KEY` for stdio |\n| **Tools** | 10 — nine financial research tools plus `register_account` |\n\n## Connect: hosted Streamable HTTP\n\nRecommended, and requires no local installation.\n\n1. [Register a free account](https://hpsilab.com/register), sign in, and\n   generate an API key from Settings.\n2. Add the server to your client's **private** configuration, replacing\n   `hpsi_your_key`. Never commit a real key or paste one into chat.\n\nThe example below is Claude Code's `.mcp.json`; other clients use different\nconfiguration schemas, all covered in\n[client setup](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/client-setup.md).\n\n```json\n{\n  \"mcpServers\": {\n    \"hpsilab\": {\n      \"type\": \"http\",\n      \"url\": \"https://hpsilab.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer hpsi_your_key\"\n      }\n    }\n  }\n}\n```\n\n3. Verify the connection:\n\n```text\nUse HPSILab to analyze AAPL. Separate observed metrics from interpretation,\nidentify conflicting signals, and finish with a concise risk summary.\n```\n\nAll financial research tools require a valid API key. See\n[authentication](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/authentication.md)\nfor key handling and rotation.\n\n## Connect: local stdio\n\nFor clients that require a local process:\n\n```bash\npip install -U hpsilab-quant-finance-mcp\n```\n\nThis example uses the `mcpServers` schema supported by Claude and Cursor; VS\nCode and GitHub Copilot use a `servers` schema instead.\n\n```json\n{\n  \"mcpServers\": {\n    \"hpsilab\": {\n      \"command\": \"hpsilab-quant-finance-mcp\",\n      \"env\": {\n        \"HPSILAB_API_KEY\": \"hpsi_your_key\"\n      }\n    }\n  }\n}\n```\n\nThen verify it through the MCP client:\n\n```text\nUse HPSILab to get the AI prediction for NVDA and summarize the model consensus.\n```\n\nThe client discovers tools with MCP `tools/list` and invokes them with\n`tools/call`. See\n[local setup](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/self-hosting.md)\nand\n[Python usage](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/python-sdk.md),\nwhich also covers calling the tool functions directly from Python.\n\n## Tools\n\nNine financial research tools, plus `register_account`. Tool names and parameter\nmeanings are part of the public compatibility contract.\n\n| Tool | What it returns | Behavior |\n| --- | --- | --- |\n| `analyze_stock` | Aggregate directional and quantitative stock analysis | Read-only |\n| `get_ai_prediction` | Next-session prediction, confidence, and model consensus | Read-only |\n| `get_iv_radar` | IV level, rank, percentile, skew, and regime | Read-only |\n| `get_option_pressure` | Max pain, gamma walls, expected move, and pressure zones | Read-only |\n| `get_monte_carlo` | 30-day simulated distribution and probabilities | Read-only |\n| `get_equity_curve` | Strategy backtests and risk-adjusted performance | Read-only |\n| `get_pretrade_risk_scan` | Position, exposure, correlation, and risk checks | Read-only |\n| `generate_stock_images` | Hosted stock and options chart artifacts | Creates an artifact; not idempotent |\n| `generate_stock_research_report` | Structured Markdown research report and timestamp | Creates an artifact; not idempotent |\n| `register_account` | Account credentials for the authenticated caller | Creates an account and sends email; not idempotent |\n\nResearch tools accept one exchange ticker such as `NVDA`, `SPY`, or `BRK.B`;\ncompany names are not accepted. Live results can change between calls. Artifact\ntools can consume quota and should not be retried automatically.\n\nFull inputs, outputs, side effects, and tool-selection guidance are in\n[docs/tools.md](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/tools.md).\n\n### Monte Carlo research example\n\n![PLTR Monte Carlo scenario visualization](https://raw.githubusercontent.com/haiyunsky/hpsilab-quant-finance-mcp/main/assets/pltr-monte-carlo-scenarios.png)\n\nExample visualization of scenario-based Monte Carlo research output. Results\ndepend on the selected inputs and model assumptions. See\n[`get_monte_carlo`](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/tools.md#financial-research-tools)\nfor tool details.\n\n## Copy-ready prompts\n\n### Claude\n\n```text\nUse HPSILab to analyze NVDA. Summarize the directional signal, AI model\nconsensus, IV regime, options pressure, 30-day Monte Carlo range, and the\nthree most important risks. Distinguish tool data from interpretation.\n```\n\n### Cursor\n\n```text\nUse HPSILab's IV radar and option-pressure tools for SPY. Compare IV rank,\npercentile, skew, expected move, max pain, gamma wall, and pressure zones.\nReturn a compact table and do not recommend a trade.\n```\n\n### ChatGPT\n\n```text\nRun the HPSILab pre-trade risk scan for TSLA. Explain every warning or failed\ncheck, preserve unavailable fields as unavailable, and quote the returned\nreason instead of guessing. Do not execute or recommend a trade.\n```\n\nSetup guidance covers ChatGPT, Claude, Cursor, VS Code, GitHub Copilot,\nContinue, and Kimi. See the\n[client setup guide](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/client-setup.md)\nfor each client's transport and configuration format.\n\n## Errors, retries, and limits\n\nEvery failure is a structured object with a stable `error_code`, never prose an\nagent has to pattern-match. Five refusals matter, because each has a different\nremedy:\n\n| `error_code` | Meaning | What resolves it |\n| --- | --- | --- |\n| `api_key_required` | No key is configured | Registering. Nothing is sent downstream |\n| `rate_limited` | Calling too fast (429) | Waiting — `next_actions` carries the seconds |\n| `insufficient_credits` | The Credit balance is empty (402) | Adding Credits, or registering for trial Credits |\n| `allowance_exhausted` | The free evaluation ceiling is spent (402) | Registering, or verifying an email. Money does not lift it |\n| `settlement_unknown` | A payment whose outcome is unconfirmed | Reconciliation. **Do not retry it and do not pay again** |\n\nWithout a key the package stops locally, before constructing the downstream\nclient or sending a request:\n\n```json\n{\n  \"error\": \"api_key_required\",\n  \"message\": \"A free API key is required.\",\n  \"register_url\": \"https://hpsilab.com/register\",\n  \"docs_url\": \"https://hpsilab.com/developer/v2\"\n}\n```\n\n401 and 402 responses are never retried. A 429 is retried only when it carries a\nvalid `Retry-After`. Read-only calls use a finite retry budget for timeouts and\nrecoverable 500/502/503/504 responses; artifact-producing calls are not retried\nautomatically. The package also applies one process-local safeguard of 10\nrequests per rolling minute per API key — burst protection, not a quota, since\nonly the hosted service knows the balance and the plan.\n\nField-by-field payloads, the Credits circuit breaker, and the reasoning behind\neach remedy are in\n[docs/authentication.md](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/authentication.md)\nand\n[docs/python-sdk.md](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/docs/python-sdk.md).\n\n## Why HPSILab\n\nHPSILab gives assistants typed inputs, structured outputs, ticker validation,\nmachine-readable errors, and dedicated tools instead of invented metrics. It\nsupports US-listed equities, ETFs, and supported options data; coverage and\nlimits depend on the hosted service and plan.\n\n## Safety and license\n\nHPSILab is for research and education only. Outputs may be incomplete, delayed,\nor wrong and are not investment, financial, or trading advice. The MCP server has\nno brokerage connectivity, order entry, or trade-execution capability.\n\nLicensed under the\n[MIT License](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/LICENSE).\nContributions are welcome; read\n[AGENTS.md](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/AGENTS.md)\nand\n[CONTRIBUTING.md](https://github.com/haiyunsky/hpsilab-quant-finance-mcp/blob/main/CONTRIBUTING.md)\nbefore proposing public schema changes.\n",
  "bytes": 9896,
  "sha": "9cea9fb2227716bb1a511e6b10a0f3cf364d2cd1642e232d6aa5ad1e6f7e0000",
  "repo_slug": "haiyunsky/hpsilab-quant-finance-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_haiyunsky_hpsilab_quant_financ_254acf99/readme"
}