gexbot-mcp

一个轻量级 MCP 服务器，封装了 GEXBot API，以便在 claude.ai 中作为自定义连接器添加。

使用官方 MCP Python SDK（FastMCP）构建，通过 Streamable HTTP 提供服务，因此可以远程托管（例如在 Render 上）。

规范参考：nfa-llc/gexbot-openapi — 基础 URL https://api.gex.bot/v2，Bearer 令牌认证。

暴露的工具

另外还有一个普通的 HTTP GET /health 端点（不是 MCP 工具），用于正常运行时间检查 / Render 健康检查。

关于 dte

GEXBot 不接受任意的 DTE 整数 — 它将数据分入固定的类别。此服务器将 dte 参数映射到这些类别：

• dte=0 → zero（下一个到期日 / 0DTE）

• dte=1 → one（下一个到期日 + 1）

• 任何其他值 → full（所有已发布到期日的完整聚合，最长约 90 天）

你关心的代码

没有硬编码限制 — GEXBot 支持的任何代码都可以使用（参见 list_tickers()）。你可能会最常使用：QQQ、SPY、NDX、SPX、SPXW。

Related MCP server: ai-trader

认证

服务器在请求时从环境中读取 GEXBOT_API_KEY，并将其作为 Authorization: Bearer <key> 发送给 GEXBot。密钥永远不会硬编码 — 必须在运行此服务的任何地方（本地、Docker 或 Render）将其设置为环境变量。

本地运行

python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt

set GEXBOT_API_KEY=gexbot_custom_your_key_here   # cmd.exe
# or: $env:GEXBOT_API_KEY = "gexbot_custom_your_key_here"   # PowerShell

python server.py

服务器默认监听 http://0.0.0.0:8000（可通过 PORT 覆盖）。MCP 端点在 /mcp；健康检查在 /health。

快速检查：

curl http://localhost:8000/health

使用 Docker 运行

docker build -t gexbot-mcp .
docker run -p 8000:8000 -e GEXBOT_API_KEY=gexbot_custom_your_key_here gexbot-mcp

部署到 Render（免费套餐）

1. 将此文件夹推送到 GitHub（或 GitLab）仓库。

2. 在 Render 仪表板中：New + → Web Service → 连接你的仓库。

   • Render 会自动检测 Dockerfile。将构建/启动命令留空（Docker 会处理）。

   • 或者，如果你更喜欢一键配置，此仓库包含 render.yaml — 使用 New + → Blueprint 并指向该仓库。

3. 将 Instance Type 设置为 Free。

4. 在 Environment 下，添加：

   • GEXBOT_API_KEY = 你的密钥（将其标记为 Secret）。请在 Render 仪表板中自行粘贴 — 不要将其放入仓库或 render.yaml 中。

5. Health Check Path：/health。

6. 部署。Render 将构建 Docker 镜像并为你提供一个 URL，例如： https://gexbot-mcp.onrender.com

注意：Render 的免费 Web 服务在闲置 15 分钟后会关闭，并在下一次请求时大约需要 30-60 秒重新唤醒 — 闲置后的第一次工具调用可能会很慢。

在 claude.ai 中添加为自定义连接器

1. 在 claude.ai 中：Settings → Connectors → Add custom connector。

2. URL：https://<your-app>.onrender.com/mcp

3. 保存。Claude 将发现这三个工具（get_gex_levels、get_gex_profile、list_tickers）。

错误处理

所有工具都返回紧凑的 JSON 字典。失败时返回 {"error": "<message>", ...} 而不是抛出异常，以便模型能够看到并转述问题。已处理的情况：

• API 密钥错误/缺失 → GEXBot 返回 401 → 清晰的“检查 GEXBOT_API_KEY”消息。

• 密钥无权访问资源 → 403 → 清晰的消息。

• 不支持的代码 → 404 → 清晰的消息。

• 错误请求（例如格式错误的代码/类别）→ 400 → 显示 GEXBot 的错误消息。

• GEXBot 故障 / 市场关闭的边界情况 → 5xx 已处理并给出清晰消息；此外， get_gex_levels / get_gex_profile 在返回数据的时间戳超过 24 小时时会包含 "stale": true 标志，因为 GEXBot 本身没有明确的“市场关闭”错误。

• 网络/超时错误 → 清晰的消息，不会向客户端泄露堆栈跟踪。

项目结构

server.py         # the MCP server (FastMCP, Streamable HTTP)
requirements.txt
Dockerfile
render.yaml        # optional Render Blueprint config
.env.example