GammaRips Options Intelligence

GammaRips MCP 服务

为 AI Agent 提供期权资金流情报基础工具。

每个交易日晚间，GammaRips 会按流动性对 3,532 只可交易期权的美国标的进行排名，选出前 100 只，保留看涨标的，并为每只标的定价一份虚值看涨期权。这样就得到一个约含 40 到 50 份合约的池子，供 Agent 实际交易。这个 MCP 服务为自带 Agent 的交易者提供该合约池，以及用于分析的基础数据：时点特征、已实现的机会曲面（最大有利／最大不利波动，不应用任何退出规则）、区间交易结果标签、市场状态背景和方法论操作手册。

更优质的合约，数据说话。 自流动性规则于 2026-08-24 生效以来（1,301 份合约），合约池的未平仓量中位数为 4,664，交易时段成交量中位数为 1,039，而此前 60 个扫描日分别为 906 和 232。流动性最低的 10% 合约未平仓量仍达 1,635，而此前仅为 29。在一项为期 60 天的研究中，10:00 ET 入场时无法成交的比例从 40.5% 降至 6.1%。流动性充足的合约，才能让你在接近报价时买入和卖出。

设计原则：只提供基础工具，不荐股。 这里没有“我应该买什么”的接口。每个 Agent 都基于相同数据进行分析，并自行选择合约和退出方式。数据来自模拟交易研究；仅供教育用途；不构成投资建议。

托管的 MCP 端点

• Streamable HTTP（主要）： https://mcp.gammarips.com/mcp
• SSE（旧版，计划弃用）： https://mcp.gammarips.com/sse
• 无状态 JSON-RPC： https://mcp.gammarips.com/jsonrpc
• 服务卡片： https://mcp.gammarips.com/.well-known/mcp/server-card.json
• OAuth 端点（聊天客户端）： https://mcp.gammarips.com/pro。同一 服务，同样的 9 个工具，但需要凭据。因此，添加该服务时，ChatGPT、Claude （claude.ai / Desktop）、Cursor，以及任何支持 OAuth 2.1 的 MCP 客户端 都会提供 GammaRips 登录选项。订阅等级会随令牌传递。发现端点：/.well-known/oauth-protected-resource/pro； 授权服务器：https://gammarips.com。
• 身份验证： 两种凭据，同一套分级。(1) API 密钥：gr_live_...，通过 Authorization: Bearer <key>（或 X-API-Key）传递，适用于可发送 请求头的客户端。(2) OAuth 2.1 访问令牌：由 gammarips.com 在你登录后 （聊天客户端）或由机器客户端通过 client_credentials 签发 （无头 Agent，见下文）。免费层工具无需任何凭据即可通过 /mcp 使用； 4 个专业版工具需要任一凭据对应的有效订阅。强制执行 已启用。请访问 gammarips.com/pricing 开通权限。

可用工具（9 个）

V4（2026-07-17）将 V3 的 29 个工具整合为 9 个。被整合的工具以这 9 个工具的 view= / granularity= 模式继续提供。web_search 已移除。

免费层级（无需密钥）：get_pool、get_regime_context、 get_market_calendar_status、get_playbook、get_daily_report。 Pro 层级（Agent Access，$29/月密钥）：get_signal、get_liquidity、 query_outcomes、replay_contract。

• get_pool （免费） — 候选池：view="enriched"（精选叙述/技术指标/合约/mom_60，防止数据泄漏的视图；默认值）、 "raw"（精选前的扫描结果）、"features"（来自允许列表视图的时点特征向量）、 "preview"（公开预览）。
• get_signal （Pro） — 单个代码：view="detail"（完整增强信息， 默认值）或 view="earnings"（策略的财报窗口检查）。
• get_liquidity （Pro） — 最新入场日流动性：单个 contract （优先使用缓存，设置 live=true 强制请求上游），或一次调用获取整个池 / contracts 候选列表。本数据方案不包含报价字段。
• query_outcomes （Pro） — 结果与凭证数据基础，通过 view= 选择： labels（行级区间标签 + 特征；默认值）、summary（分组聚合）、 surface（每份合约的 MFE/MAE 波动范围，不含退出 — aggregate_only=True 会返回整个窗口的 MFE/MAE 分位数；这是退出设计应使用的模式，因为行模式上限为 200 行，并通过 truncated / matched_rows / partial_scan_date 声明截断情况）、 harvest（触及概率曲线）、exit_rule（评估你自己的区间/追踪规则）、 signal_performance / win_rate（标的方向表现，不是期权盈亏）、 positions / performance（引擎已实现的模拟交易凭证，按队列筛选）。实时队列由 V7_1_TILTED_GIGO 以及入场日期不早于 cohort_start（2026-08-10） 这两个条件共同定义，响应现在会携带这些信息——仅凭策略标签无法定义队列， 因为账本会在同一标签下保留已弃用的队列。重置后，实时队列为空是正常情况： total_trades: 0 且聚合值为 null 表示“尚未累计已平仓交易”， 而不是“胜率为 0%”。policy_version="all" 会涵盖所有时期，但也包括引擎已弃用的队列——不能作为业绩记录。
• replay_contract （Pro） — 用于自定义退出规则的原始价格序列： granularity="minute"（盘中路径 + 精确的首次越界时间；默认值）或 "day"（每日 OHLCV 标记序列）。此服务不会模拟退出。
• get_regime_context （免费） — 截至扫描日期的 VIX/VIX3M/SPY 趋势 + 故障时关闭的市场状态护栏。
• get_market_calendar_status （免费） — view="status"（NYSE 开盘/收盘状态， 默认值）、view="scan_dates"（哪些扫描日期有数据）或 view="freshness"（候选池是否正确：预期扫描日期、各流水线阶段的状态、 get_pool 提供的扫描日期，以及包含机器可读 reasons 的故障时关闭 fresh 标志）。
• get_playbook （免费） — 方法说明 + 参考资料：不带参数时列出目录；使用 name= 获取策略手册（start-here、daily-workflow、 run-your-own-tournament、exit-lab、leakage-and-data-contract、 changelog），或使用 name="schema" 获取机器可读的数据契约（逐列标注数据泄漏分类）；field= 可解释任意信号字段（确定性，不使用 LLM）。策略手册也可作为 MCP 资源使用（gammarips://playbooks/{name}）。
• get_daily_report （免费） — view="report"（完整每日报告，默认值） 或 view="list"（近期报告）。

已移除

web_search（V4）。引擎每日自行选出的标的不在当天发布（get_todays_pick / list_todays_picks / get_open_position 已在 V3 移除）；已实现的交易凭证仍可通过 query_outcomes(view="positions") 获取。

提示词

morning_brief、analyze_candidate(ticker)、run_your_own_tournament — 对上述工具进行轻量编排。均不会返回标的推荐。

快速连接

Claude Code

# Free tier (no key):
claude mcp add --transport http gammarips https://mcp.gammarips.com/mcp

# Pro (with your key):
claude mcp add --transport http gammarips https://mcp.gammarips.com/mcp \
  --header "Authorization: Bearer gr_live_your_key"

# Pro with OAuth instead of a key (sign in once in the browser, tokens refresh):
claude mcp add --transport http gammarips https://mcp.gammarips.com/pro
# then run /mcp inside Claude Code and choose "Authenticate"

ChatGPT、Claude（claude.ai / Desktop）及其他 OAuth 聊天客户端

添加自定义连接器 / 远程 MCP 服务，URL 为 https://mcp.gammarips.com/pro。客户端会发现授权服务器 （gammarips.com），注册自身（Client ID Metadata Document 或动态注册），并打开 GammaRips 登录与授权页面。无需粘贴密钥。 尚未订阅？连接仍可使用免费工具，专业版工具会返回订阅步骤；订阅后，专业版访问权限会在下一次令牌刷新时（1 小时内）生效，或者在重新连接时生效。

无头 Agent（虚拟机、定时任务、服务器）：机器客户端

对于没有浏览器、也没有人工参与的 Agent，请在 gammarips.com/account 创建机器客户端（需要 Agent Access）。 你会获得一个 client_id 和 client_secret（仅显示一次）。使用 client_credentials 授权方式获取有效期为 1 小时的访问令牌，并将其作为 bearer 发送：

TOKEN=$(curl -s -u "$GR_CLIENT_ID:$GR_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://mcp.gammarips.com/pro \
  https://gammarips.com/oauth/token | jq -r .access_token)

# Claude Code headless (claude -p), with the token in .mcp.json:
#   { "mcpServers": { "gammarips": { "type": "http",
#       "url": "https://mcp.gammarips.com/pro",
#       "headers": { "Authorization": "Bearer ${GAMMARIPS_MCP_TOKEN}" } } } }
GAMMARIPS_MCP_TOKEN="$TOKEN" claude -p "..." 

每次运行前都要获取令牌：机器客户端没有刷新令牌，而且每次获取令牌时都会重新读取你的订阅等级。API 密钥仍可用于相同用途；机器客户端则是短期凭证方案。

Cursor

最简单的方式——安装插件。 此仓库是符合 Open Plugins 标准的插件（.cursor-plugin/plugin.json）：它捆绑了托管 MCP 服务，以及一个 gammarips-options-flow 技能，用于指导 Agent 遵循数据而非建议的工作流。可从插件市场安装（搜索“GammaRips”），或让 Cursor 指向此仓库。开箱即可连接免费层级；添加你的 gr_live_... 密钥即可使用专业版工具。

手动配置：Settings → MCP → Add new MCP server，或添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "gammarips": {
      "url": "https://mcp.gammarips.com/mcp",
      "headers": { "Authorization": "Bearer gr_live_your_key" }
    }
  }
}

免费层级请省略 headers。

Cline

MCP Servers → Remote Servers → Add，或添加到 cline_mcp_settings.json：

{
  "mcpServers": {
    "gammarips": {
      "url": "https://mcp.gammarips.com/mcp",
      "type": "streamableHttp",
      "headers": { "Authorization": "Bearer gr_live_your_key" }
    }
  }
}

免费层级请省略 headers（5 个匿名工具）。

通用 MCP 配置

{
  "mcpServers": {
    "gammarips": {
      "url": "https://mcp.gammarips.com/mcp"
    }
  }
}

仅支持 SSE 的客户端可在弃用期内使用旧版 /sse 端点。

免费层级无需账户即可使用：get_pool、get_regime_context、get_market_calendar_status、get_playbook、get_daily_report。专业版工具（get_signal、get_liquidity、query_outcomes、replay_contract）需要 Agent Access（每月 29 美元，免费试用 30 天）——在 gammarips.com 生成密钥，或通过 /pro 连接并登录。

本地开发

先决条件

• Python 3.10+
• 可选：Docker

设置

git clone https://github.com/DevDizzle/gammarips-mcp.git
cd gammarips-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env

本地运行

PYTHONPATH=src python src/server.py

服务器绑定到 0.0.0.0:${PORT:-8080}，在 /mcp 提供 Streamable HTTP（SSE 回退）。

Docker

docker build -t gammarips-mcp .
docker run --rm -p 8080:8080 --env-file .env gammarips-mcp

环境

当前环境变量请参阅 .env.example。常见值包括：

• GCP_PROJECT_ID
• FIRESTORE_DATABASE
• GCS_BUCKET_NAME
• LOG_LEVEL
• PORT
• REQUIRE_API_KEY / AUTH_SHADOW（API 密钥门控模式）
• OAUTH_ENABLED / OAUTH_ISSUER / OAUTH_JWKS_URL / OAUTH_MCP_RESOURCE_ORIGINS （OAuth 2.1 资源服务器；默认值为生产环境配置，参见 src/utils/oauth.py）

验证

Python 编译检查

python -m compileall src

Docker 构建检查

docker build -t gammarips-mcp:test .

部署

部署为手动操作（已移除 CD 工作流；.github/workflows/ci.yml 仅在向 main 推送或提交 PR 时运行 ruff format --check + ruff check）。

使用部署脚本发布新版本。该脚本使用 Cloud Run 源代码部署，并精确复现线上配置（密钥通过 Secret Manager 管理， REQUIRE_API_KEY=false）：

bash scripts/deploy.sh

等效的单行命令：

gcloud run deploy gammarips-mcp --source=. \
  --project=profitscout-fida8 --region=us-central1 \
  --set-env-vars="REQUIRE_API_KEY=false" \
  --set-secrets="POLYGON_API_KEY=POLYGON_API_KEY:latest,GOOGLE_API_KEY=GOOGLE_API_KEY:latest,GOOGLE_CSE_ID=GOOGLE_CSE_ID:latest"

API 密钥通过 Secret Manager 挂载——切勿将其作为普通环境变量传递 （这会覆盖密钥挂载）。

任何会改变数据暴露范围的部署之前，都要运行 gammarips-review 泄露审计（参见 docs/MCP-V3-SPEC.md §2.4）。

安全

有关信任模型，请参阅 SECURITY.md — 只读保证、参数化查询防范 SQL 注入、响应大小上限、按 IP 限流、经过清理的错误信息、防泄露视图、列分类数据契约，以及 OAuth 2.1 资源服务器模型（此服务仅验证令牌；gammarips.com 是授权服务器）。

许可证

MIT