sportwizzard

SportWizzard MCP 服务

从任何支持 MCP 的 AI Agent（Claude Code、Claude Desktop、Codex、Cursor，……）查询来自 35+ 家体育博彩运营商和 DFS 应用的实时体育博彩数据——赔率、球员特别投注、正期望值（+EV）机会、套利、统计数据和参考数据。

通过 SportWizzard REST v1 API 提供 20 个只读工具，有两种使用方式：托管远程服务（无需安装）和通过 npx 运行的 stdio 服务。在 https://sportwizzard.com/account 免费获取 API 密钥（API Keys 选项卡——无需银行卡）。

托管服务（推荐——无需安装）

claude mcp add --transport http sportwizzard https://mcp.sportwizzard.com/mcp \
  --header "Authorization: Bearer sw_live_your_api_key_here"

codex mcp add sportwizzard --transport http --url https://mcp.sportwizzard.com/mcp \
  --header "Authorization: Bearer sw_live_your_api_key_here"

托管服务是一个轻量代理：你的密钥会转发到 SportWizzard API，由该 API 执行身份验证和速率限制。两种传输方式均支持全部 20 个工具。（托管服务上的 download_snapshot 会返回 CDN 下载 URL 和一条可直接运行的命令，由你的 Agent 在本地执行；stdio 服务则会直接写入文件。）

成功通过身份验证的实时工具调用会尽力发送账户用量回执。 测量请求不包含工具参数或结果数据。 对于托管服务上的 download_snapshot，成功的 CDN HEAD 检查也会计入，因为该工具已验证返回的下载 URL 可访问；HEAD 检查失败则不会计入。

Stdio（本地）

npx -y sportwizzard-mcp

Claude Code：

claude mcp add sportwizzard -e SPORTWIZZARD_API_KEY=sw_live_your_api_key_here -- npx -y sportwizzard-mcp

Claude Desktop（claude_desktop_config.json — macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "sportwizzard": {
      "command": "npx",
      "args": ["-y", "sportwizzard-mcp"],
      "env": { "SPORTWIZZARD_API_KEY": "sw_live_your_api_key_here" }
    }
  }
}

模拟模式（无需密钥，无需网络）

设置 SPORTWIZZARD_MOCK=1 以获取预置的示例响应——可在获取密钥前用于搭建集成。

配置

环境变量	默认值	用途
SPORTWIZZARD_API_KEY	(无)	你的 API 密钥，通过 X-Api-Key 发送。
SPORTWIZZARD_BASE_URL	https://api.sportwizzard.com	覆盖 API 基础 URL。
SPORTWIZZARD_MOCK	(关闭)	1 = 使用预置示例数据，不连接网络。

工具

工具	功能
list_events / get_event	赛事/赛程——可按联赛、球队、状态、时间筛选；提供完整详情，包括天气、阵容和预计先发投手。
get_event_stats	单场赛事的比赛数据：每位球员的统计数据和球队赛果。
get_odds / get_event_odds / get_player_odds / get_team_odds	当前赔率，可按赛事、球员、球队、体育博彩运营商、市场或联赛筛选。get_odds 还接受 scope：event（比赛市场）、season（赛季期货）、tournament（高尔夫/网球冠军投注）；省略则返回全部。
get_edges	相对于去除水钱后的公平市场赔率的 +EV 机会（可按联赛、来源、最小优势筛选）。
get_arbitrage	套利机会及其投注选项和投注比例（双向/三向）。
list_players / list_teams / get_player_stats / get_team_stats	参考数据以及赛季/历史统计数据。
get_player_game_logs	批量逐场统计数据——用于模型训练的数据源。
download_snapshot	将完整实时赔率盘保存到磁盘（gzip 压缩后数十 MB）。include_history: true 还会填充每个投注选项的 priceHistory（相同架构；固定消耗 5 个额度，而非 1 个）。
list_sportsbooks / list_leagues / list_markets / status	查看来源 ID、覆盖的联赛和支持的市场类型；检查客户 API 的可用性。
get_account_usage	你的套餐级别、速率限制和月度用量。

每个响应都使用封装 { success, data, nextCursor, meta }；存在 nextCursor 时，工具会附加 _paging 提示，让 Agent 知道需要继续获取数据。

Futures（赛季范围市场）

get_odds 搭配 scope=season 会返回整个赛季的 futures——分区／联盟／冠军得主、奖项赔率、球队胜场总数、赛季领跑者和整个赛季的球员特殊投注。以下三个正交维度用于描述这些市场：

• marketScope — 市场所依附的锚点：SEASON 或 TOURNAMENT。普通比赛行中完全不会出现此字段。
• period — 锚点内的时间窗口：REG_SEASON（常规赛结束时结算）或 FULL（持续到季后赛结束）。
• segment — 比赛的哪个部分：AFC_EAST、NL、SEC 等。仅当市场按分组划分时才会出现，且不可或缺：全部 32 个 NFL DIVISION_WINNER 选项共用一个赛季锚点 eventId，因此没有 segment 时，它们看起来会像是一场由 32 支球队参加的比赛，而不是 8 个分区。

注意：得主／奖项市场是类别型市场（每位竞争者各有一个 YES 选项，teamSide: "NONE"，通常没有 NO 选项）；futures 行中的 eventStartTime 是赛季锚点／结算日期，不是开赛时间；同一赛事的所有博彩公司 futures 共用同一个赛季 eventId；而 futures 会被特意排除在 get_edges／get_arbitrage 之外（不会参与去水或优势计算）。范围匹配是精确的——season 不包含 TOURNAMENT，无效值会返回 HTTP 400，并指出有效值。

源码

git clone https://github.com/sportwizzard/sportwizzard-mcp.git
cd sportwizzard-mcp && npm install && npm run build
SPORTWIZZARD_MOCK=1 node dist/index.js   # or set SPORTWIZZARD_API_KEY

维护者

此 README 随 npm 包一起发布，因此请勿在其中写入内部 主机名、密钥和私人备注（此仓库为公开仓库）。

布局。 src/index.ts 是 stdio 入口（dist/index.js，npm bin）；src/httpServer.ts 是托管的 Streamable HTTP 入口（无状态，每个 POST 处理一个请求；包含 Host 允许列表和 bearer 密钥处理）；src/auth.ts 会验证调用者的密钥是否与 API 匹配、缓存密钥并应用每个密钥的速率限制； src/tools.ts 和 src/server.ts 用于定义和注册工具；src/client.ts 是 REST 客户端，src/mock.ts 提供 SPORTWIZZARD_MOCK=1 时使用的数据。 tests/stdio-smoke.mjs 和 tests/http-smoke.mjs 是针对环回 mock API 的端到端冒烟测试（无需凭据，不会调用生产环境）。

构建和验证（PR 检查 .github/workflows/ci.yml 会执行相同的打包与冒烟测试，以及不推送镜像的容器构建）：

npm ci --ignore-scripts && npm run build
release_dir="$(mktemp -d)"
npm pack --ignore-scripts --pack-destination "$release_dir"
npm install --prefix "$release_dir/consumer" --omit=dev --ignore-scripts --no-audit --no-fund "$release_dir"/*.tgz
npm run smoke -- "$release_dir/consumer/node_modules/sportwizzard-mcp/dist/index.js" "$release_dir/smoke.json" "$release_dir"/*.tgz
npm run smoke:http -- "$release_dir/consumer/node_modules/sportwizzard-mcp/dist/httpServer.js" "$release_dir/http-smoke.json"
rm -rf "$release_dir"

stdio 冒烟测试会检查 tools/list、get_odds scope=season 转发，以及带历史记录的快照下载；HTTP 冒烟测试会检查 /healthz、密钥拒绝、Host 允许列表、tools/list、密钥转发，以及干净的 SIGTERM 退出。两项测试都能验证传输和打包，而非实时数据质量。

发布。

• 托管服务：publish-container.yml 会在每次推送到 main 时发布带 SHA 标签的 GHCR 镜像。只有在 Ops 的 deployment/releases/api.yaml 行中提升该摘要后才会部署；该行负责管理部署位置、限制和凭据引用。
• npm 包：更新 package.json 中的 version，运行 npm install --package-lock-only，同步 server.json，合并到 main，然后 手动运行 Publish npm package 工作流（publish-npm.yml）。该工作流只构建一次，对打包后的 tarball 执行冒烟测试，并通过 npm trusted publishing（OIDC；无需 npm token）发布完全相同的文件。 发布 npm 包不会更新托管容器。

注意事项。 托管运行时设置包括 MCP_HTTP_PORT（默认值为 8091）、 MCP_ALLOWED_HOSTS、AUTH_CACHE_TTL_MS、RATE_LIMIT_PER_MIN、 SPORTWIZZARD_SNAPSHOT_URL 和 SPORTWIZZARD_SNAPSHOT_HISTORY_URL，以及上述客户设置。download_snapshot 在 stdio 模式下会写入文件，但在托管服务上会返回 CDN URL 和命令。切勿打印或提交 ~/.npmrc。未完成的工作请记录为此仓库中的 GitHub issues。

许可证

MIT © SportWizzard LLC