HPSILab Quant Finance

HPSILab 股票与期权分析量化金融 MCP 服务

为 AI Agent 提供股票与期权风险分析。连接一个远程 MCP 端点 https://hpsilab.com/mcp，通过 OAuth 登录（无需粘贴 API 密钥），Agent 即可调用：

• 交易前风险扫描：对照 SPY 检查波动率、贝塔、回撤和 VaR，并应用固定的通过／警告／失败限值，同时检查仓位规模、行业敞口和相关性；
• 期权结构：IV 水平、排名和偏斜、伽马墙、看涨／看跌墙、最大痛点；
• 10 个交易日的蒙特卡洛价格区间以及收盘价走高的概率；
• analyze_stock 一次调用即可获取概览，以及 AI 预测和回测。

结果为结构化 JSON，包含机器可读错误，适用于美国上市股票、ETF 和受支持的期权。本仓库提供开源 Python 服务（MIT）；托管端点运行相同的工具集。

仅供研究和教育用途。HPSILab 不提供投资建议，也不执行交易。

获取免费 API 密钥 · 定价 · 工具参考 · 客户端设置 · Python SDK

注册表名称	io.github.haiyunsky/hpsilab-quant-finance-mcp
版本	0.11.1 — 源码检出版本显示为 0.11.1+source
传输方式	Streamable HTTP（托管） · stdio（PyPI 软件包）
远程端点	https://hpsilab.com/mcp
软件包	pip install -U hpsilab-quant-finance-mcp
身份验证	OAuth 登录或 Bearer API 密钥（托管），HPSILAB_API_KEY（stdio）
工具	10 个——九个金融研究工具，以及 register_account

连接：托管 Streamable HTTP

推荐方式，无需本地安装。

使用 OAuth 登录

支持 MCP OAuth 的客户端（Claude Code、Claude.ai 和 ChatGPT 连接器等）只需提供 URL；首次使用时，它们会打开 HPSILab 登录页面。

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

在连接器界面中，使用 URL https://hpsilab.com/mcp 添加自定义连接器。

使用 API 密钥

对于不支持 OAuth 的客户端或脚本：

1. 注册免费账户，登录，然后在 Settings 中 生成 API 密钥。
2. 将服务添加到客户端的私有配置中，并替换 hpsi_your_key。切勿提交真实密钥或将其粘贴到聊天中。

以下示例使用 Claude Code 的 .mcp.json；其他客户端使用不同的 配置架构，详见 客户端配置。

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

3. 验证连接：

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

所有金融研究工具都需要使用已登录账户：通过 OAuth 登录或提供有效的 API 密钥。有关密钥处理和轮换，请参阅 身份验证。

正在构建 Agent？examples/agents 提供了适用于 OpenAI Agents SDK、Claude Agent SDK 和 LangGraph 的单文件风险检查 Agent。操作指南： docs/guide-risk-gate-for-trading-agents.md。

连接：本地 stdio

适用于需要本地进程的客户端：

pip install -U hpsilab-quant-finance-mcp

此示例使用 Claude 和 Cursor 支持的 mcpServers 架构；VS Code 和 GitHub Copilot 则使用 servers 架构。

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

然后通过 MCP 客户端验证：

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

客户端通过 MCP tools/list 发现工具，并通过 tools/call 调用工具。参阅 本地配置 和 Python 用法， 其中也介绍了如何直接从 Python 调用工具函数。

工具

九种金融研究工具，另加 register_account。工具名称和参数含义 属于公开兼容性约定。

工具	返回内容	行为
analyze_stock	汇总方向性和量化股票分析	只读
get_ai_prediction	下一交易时段预测、置信度和模型共识	只读
get_iv_radar	IV 水平、排名、百分位、偏斜和状态	只读
get_option_pressure	最大痛点、Gamma 墙、预期波动和压力区间	只读
get_monte_carlo	10 个交易日的模拟分布和概率	只读
get_equity_curve	策略回测和风险调整后表现	只读
get_pretrade_risk_scan	持仓、敞口、相关性和风险检查	只读
generate_stock_images	托管的股票和期权图表产物	创建产物；非幂等
generate_stock_research_report	结构化 Markdown 研究报告和时间戳	创建产物；非幂等
register_account	尚无 API 密钥时从客户端注册，或为现有账户生成新密钥	创建账户并发送电子邮件；非幂等

研究工具接受单个交易所代码，例如 NVDA、SPY 或 BRK.B； 不接受公司名称。实时结果可能因调用而异。产物工具可能消耗配额， 不应自动重试。

完整的输入、输出、副作用和工具选择指南见 docs/tools.md。

Monte Carlo 研究示例

基于情景的 Monte Carlo 研究输出示例。结果取决于所选输入和模型假设。有关 工具详情，请参阅 get_monte_carlo。

可直接复制的提示词

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.

设置指南涵盖 ChatGPT、Claude、Cursor、VS Code、GitHub Copilot、 Continue 和 Kimi。有关每个客户端的传输方式和配置格式，请参阅 客户端设置指南。

错误、重试和限制

每次失败都会返回包含稳定 error_code 的结构化对象，而不是需要 Agent 通过模式匹配来判断的文字。以下五种拒绝值得关注，因为每种情况都有不同的解决办法：

error_code	含义	解决方法
api_key_required	未配置密钥	注册。不会向下游发送任何内容
rate_limited	调用过于频繁（429）	等待 — next_actions 会提供等待秒数
insufficient_credits	Credit 余额不足（402）	充值 Credits，或注册以领取试用 Credits
allowance_exhausted	免费评估额度已用尽（402）	注册或验证电子邮件。付费无法提高此额度
settlement_unknown	付款结果尚未确认	对账。请勿重试，也不要再次付款

未配置密钥时，软件包会在本地停止，不会创建下游客户端或发送请求：

{
  "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 和 402 响应，绝不会重试。只有在 429 响应包含有效的 Retry-After 时才会重试。只读调用会对超时以及可恢复的 500/502/503/504 响应使用有限的重试次数；生成制品的调用不会自动重试。该软件包还会在进程本地实施一项保护措施：每个 API 密钥每滚动一分钟最多发送 10 个请求。这是突发流量保护，而非配额，因为只有托管服务知道余额和套餐信息。

有关逐字段的负载、Credits 熔断器以及各项解决办法的原因，请参阅 docs/authentication.md 和 docs/python-sdk.md。

为什么选择 HPSILab

HPSILab 为助手提供类型化输入、结构化输出、股票代码验证、机器可读错误，以及专用工具，避免使用臆造指标。它支持在美国上市的股票、ETF 和受支持的期权数据；覆盖范围和限制取决于托管服务和套餐。

安全与许可证

HPSILab 仅供研究和教育使用。输出可能不完整、延迟或有误，不构成投资、金融或交易建议。MCP 服务不具备券商连接、下单或交易执行能力。

本项目采用 MIT License 授权。欢迎贡献；在提议更改公开 Schema 之前，请阅读 AGENTS.md 和 CONTRIBUTING.md。