GammaRips MCP Server

面向 AI 代理的期权流智能原语。

每个交易日早晨，GammaRips 都会扫描美国期权市场，寻找异常机构活动，并精心筛选——最终形成一个约 50 只股票的高信号 BULLISH 池。这个 MCP 服务器为自带代理的交易者提供该池以及推理所需的底层数据：时点特征、已实现的机会面（未应用退出规则的最大有利/最大不利偏移）、区间结果标签、市场环境背景和方法论手册。

设计原则：原语，而非推荐。 没有“我该买什么”的端点。每个代理都从相同的数据推理出自己的合约和自己的退出。纸面交易研究数据；仅供教育；不构成投资建议。

托管 MCP 端点

• 流式 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（无头代理，见下文）签发。免费层工具在 /mcp 上无需任何凭据即可使用；4 个专业工具需要任一凭据上的有效订阅。强制执行已生效。在 gammarips.com/pricing 获取访问权限。

Related MCP server: TickerAPI

可用工具（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。专业层（Agent Access，每月 39 美元密钥）：get_signal、get_liquidity、query_outcomes、replay_contract。

• get_pool （免费） — 候选池：view="enriched"（精选叙事/技术面/合约/mom_60，防泄漏视图；默认），"raw"（预筛选扫描），"features"（来自白名单视图的时点特征向量），"preview"（公开预览）。

• get_signal （专业） — 单个股票代码：view="detail"（完整增强，默认）或 view="earnings"（原则性财报窗口检查）。

• get_liquidity （专业） — 新鲜的入场日流动性：单个 contract（缓存优先，live=true 强制上游）或整个池 / 一个 contracts 短列表一次调用。此数据计划不提供报价字段。

• query_outcomes （专业） — 结果 + 收据底层数据，通过 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 （专业） — 用于您自己的退出规则的原始价格磁带：granularity="minute"（日内路径 + 精确首次穿越；默认）或 "day"（每日 OHLCV 标记序列）。此服务器不模拟退出。

• get_regime_context （免费） — 截至扫描日期的 VIX/VIX3M/SPY 趋势 + 故障关闭机制轨道。

• get_market_calendar_status （免费） — view="status"（NYSE 开盘/收盘，默认）或 view="scan_dates"（哪些扫描日期有数据）。

• 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 登录 + 同意页面。无需粘贴密钥。尚未订阅？连接仍然适用于免费工具，专业工具会回复订阅步骤；订阅后，专业访问将在下一次令牌刷新（一小时内）或重新连接时生效。

无头代理（虚拟机、cron、服务器）：机器客户端

对于没有浏览器和人类的代理，请在 gammarips.com/account 上创建机器客户端（需要 Agent Access）。您会获得 client_id + client_secret（仅显示一次）。使用 client_credentials 授权签发一小时访问令牌，并将其作为 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 技能，教您的代理数据而非建议的工作流程。从插件市场安装（搜索“GammaRips”）或将 Cursor 指向此仓库。它开箱即用连接免费层；添加您的 gr_live_... 密钥以使用专业工具。

手动：设置 → MCP → 添加新的 MCP 服务器，或添加到 .cursor/mcp.json：

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

免费层省略 headers。

Cline

MCP 服务器 → 远程服务器 → 添加，或添加到 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（每月 39 美元）— 在 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}，Streamable HTTP 位于 /mcp（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