SportAPI

sportapi-mcp

一个 MCP 服务，让 AI 助手（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 和其他 MCP 客户端）能够从 SportAPI 查询 Live 和 Prematch 比赛、比分、实时统计数据和赔率。开箱即用，使用演示数据，无需 API 密钥。

claude mcp add sportapi -- uvx sportapi-mcp

然后询问：“现在有哪些足球比赛正在进行？哪一方更被看好？”

此 MCP 服务免费，并采用 MIT 许可证。其背后的 SportAPI 数据服务是商业 产品：实时数据需要个人 API 密钥（获取方法）。没有密钥时， 每个工具都会返回 SportAPI 文档中的示例响应，并明确说明这一点。

功能

• 11 个只读工具，涵盖 Sport Line API：体育项目、导航菜单、国家/地区、 锦标赛、Live 和 Prematch 比赛列表、比赛日历、包含所有盘口的完整比赛详情、球队搜索、热门比赛、热门锦标赛以及密钥的账户状态。
• 节省令牌的输出：紧凑的 JSON，会移除空字段，并将赔率按每个盘口一行呈现 （"W1 1.525 | X 5.08 | W2 6.15"）。详细比赛可能包含 200 多个盘口，因此 get_match 默认返回 15 个，并支持 markets 筛选（["1X2", "Total"]）。
• 设计周到：每个请求都会经过快照缓存，以遵循 文档规定的最短更新间隔，并且不会为相同数据发送重叠请求。无论助手调用多少次，都不会有工具轮询或并行查询比赛。
• 演示模式，无需任何设置，并清楚标注（"source": "demo"），确保助手不会将快照当作实时数据呈现。
• 可操作的错误：密钥过期、体育项目不在订阅范围内、比赛已结束，或来自错误赛事类型的 game_id，都会返回简短说明，方便助手采取相应操作。
• 两个提示词：针对某项体育项目的实时投注概览，以及针对单场比赛的盘口对比（隐含 概率、博彩公司利润率、公平赔率）。
• 基于官方的 SportAPI Python 客户端 和官方的 MCP Python SDK 构建。默认使用 stdio，可选 Streamable HTTP。

可以询问的内容

演示模式下的对话示例（回答经过删节）。助手会自行选择工具。

“现在有哪些足球比赛正在进行？” → list_live_matches(sport_id=1)

数据来自 SportAPI 文档，并非实时数据。 目前有 39 场足球比赛正在进行。 Garuda Darwin 0:1 Darwin Olympic（76'，NPL Northern Territory）：Darwin Olympic 几乎锁定胜局， 赔率为 1.064。Ikonnect FA U19 0:1 Obosa U19（33'）：看好 Obosa，赔率为 1.40，平局赔率为 4.65。 Caucaia U20 — Floresta EC U20 在第 2 分钟仍未进球，Floresta 稍占优势，赔率为 2.112。

“阿森纳对阵考文垂：进球数盘口的赔率如何？” → get_match(game_id=746146992, line_type="live", markets=["Total"])

阿森纳在第 56 分钟以 3:0 领先（预期进球 1.45 对 0.03，射正 4:0）。总进球数：大于 3.5 球赔率为 1.23， 大于 4.5 球赔率为 2.09 / 小于 4.5 球赔率为 1.81，大于 5.5 球赔率为 4.41。市场预计会有第 4 个进球，但 不太看好第 5 个进球。

“曼彻斯特城下一场什么时候比赛，赔率是多少？” → search_matches(text="Manchester")，然后调用 get_match(game_id=730321837, line_type="prematch", markets=["1X2", "Total"])

曼彻斯特城 — 伯恩茅斯，英超联赛，2026 年 8 月 23 日 13:00 UTC。1X2：曼城 1.525， 平局 5.08，伯恩茅斯 6.15。大于 2.5 球赔率为 1.39，小于 2.5 球赔率为 2.72。

“本周末最重要的比赛有哪些？” → top_matches(line_type="prematch", include_odds=True)

“我的 SportAPI 密钥正常吗？我本周发出了多少个请求？” → account_status()（实时模式）

提供密钥后，同样的问题适用于订阅中包含的所有体育项目，并会使用当前数据。

安装

该服务是一个 Python 软件包（Python 3.10+）。最简单的运行方式是使用 uv：uvx 会在隔离环境中下载并运行它，无需安装。

uvx sportapi-mcp            # starts the stdio server; MCP clients launch it for you

也可以使用 pip 安装，并使用 sportapi-mcp 命令代替 uvx sportapi-mcp：

pip install sportapi-mcp

下面的 env 块均为可选项：省略即可在演示模式下启动。

Claude Desktop

一键安装： 从最新版本下载 sportapi-mcp.mcpb 并打开——Claude Desktop 会安装扩展，并询问是否提供可选的密钥和基础 URL（留空即可使用演示数据）。软件包源文件位于 mcpb/。

也可以编辑 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "sportapi": {
      "command": "uvx",
      "args": ["sportapi-mcp"],
      "env": {
        "SPORTAPI_KEY": "YOUR_API_KEY",
        "SPORTAPI_BASE_URL": "https://YOUR_API_DOMAIN"
      }
    }
  }
}

重启 Claude Desktop；SportAPI 工具就会出现在工具菜单中。

Claude Code

# demo mode
claude mcp add sportapi -- uvx sportapi-mcp

# live data, available in all your projects
claude mcp add sportapi --scope user \
  -e SPORTAPI_KEY=YOUR_API_KEY -e SPORTAPI_BASE_URL=https://YOUR_API_DOMAIN \
  -- uvx sportapi-mcp

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "sportapi": {
      "command": "uvx",
      "args": ["sportapi-mcp"],
      "env": {
        "SPORTAPI_KEY": "YOUR_API_KEY",
        "SPORTAPI_BASE_URL": "https://YOUR_API_DOMAIN"
      }
    }
  }
}

VS Code

添加到 .vscode/mcp.json。VS Code 会提示输入密钥，并将其安全存储：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sportapi-key",
      "description": "SportAPI key",
      "password": true
    }
  ],
  "servers": {
    "sportapi": {
      "type": "stdio",
      "command": "uvx",
      "args": ["sportapi-mcp"],
      "env": {
        "SPORTAPI_KEY": "${input:sportapi-key}",
        "SPORTAPI_BASE_URL": "https://YOUR_API_DOMAIN"
      }
    }
  }
}

Windsurf 和其他客户端

任何能够启动 stdio 服务的 MCP 客户端都可以使用：命令为 uvx，参数为 sportapi-mcp，环境变量见下文。对于 Windsurf， 将 Cursor 部分所示的 mcpServers 块放入 ~/.codeium/windsurf/mcp_config.json。

Streamable HTTP 和 Docker

sportapi-mcp --transport streamable-http --port 8000      # http://127.0.0.1:8000/mcp

docker build -t sportapi-mcp .
docker run -i --rm -e SPORTAPI_KEY -e SPORTAPI_BASE_URL sportapi-mcp          # stdio
docker run --rm -p 8000:8000 sportapi-mcp --transport streamable-http --host 0.0.0.0

HTTP 传输方式本身不提供身份验证：请将其限制在 localhost 上，或置于你自己的网关之后，因为任何能够访问它的人都可以使用你的密钥。

配置

变量	必需	描述
SPORTAPI_KEY	实时数据需要	你的 API 密钥。服务仅在 Package HTTP 标头中发送该密钥，不会将其放在 URL 或工具输出中。
SPORTAPI_BASE_URL	实时数据需要	你的个人 API 基础 URL，与密钥一同发放（https://YOUR_API_DOMAIN）。
SPORTAPI_LANGUAGE	否	响应语言代码，默认为 en。该语言必须已为你的密钥启用；请参阅语言。演示数据仅提供英文。

使用实时数据时，请同时设置 SPORTAPI_KEY 和 SPORTAPI_BASE_URL；演示模式下，两者都不设置。 即使已配置密钥，sportapi-mcp --demo 也会强制启用演示模式。

密钥绑定到获准使用该密钥的服务 IP 地址或网站 （身份验证与访问）。 MCP 服务通常运行在你自己的计算机上，因此请确保该地址已获准使用此密钥； account_status 会显示 SportAPI 检测到的 IP 地址。

工具

工具	可查询内容	SportAPI 方法
list_sports	当前有 Live / Prematch 比赛的运动项目及其数量	sports
get_menu	运动项目 → 国家 → 锦标赛的树状结构，包含 ID 和数量	menu
list_countries	某个运动项目中有比赛的国家	countries
list_tournaments	某个运动项目和国家的锦标赛	tournaments
list_live_matches	某个运动项目或锦标赛的 Live 比赛：比分、赛段、分钟、主要赔率。不指定运动项目时：Live 运动项目及热门 Live 比赛	events
list_prematch_matches	即将进行的比赛：“Top 50”、某个锦标赛、完整赛程，或日历（未来 2/4/6/12 小时、今天至未来 5 天）	events，日历
get_match	单场比赛：比分、Live 统计数据、所有市场及其赔率、子事件（半场、角球、罚牌等）	event
search_matches	按球队或参赛者名称查找 Live 和 Prematch 比赛	search
top_matches	最多 10 场最受欢迎的比赛（所有运动项目，或某个运动项目的 Prematch 比赛）	topmatches，toplist
top_championships	最多 12 个热门锦标赛及比赛数量	topchampionships
account_status	演示或实时模式；使用密钥时还会显示到期时间、运动项目、语言、访问模式和过去 7 天的请求数	account

提示词：live_betting_overview(sport) 和 compare_match_markets(match, markets)。

输出与 API 数据（十进制赔率、封锁的选项、市场 ID、子事件、Live 统计数据）的对应方式， 详见赔率、 比赛和 Live 统计数据数据模型。 get_match(include_pointers=true) 会添加每个选项的 oc_pointer，这是SportAPI Coupon API等投注系统用于下注的代码。

演示模式覆盖范围

演示模式提供 SportAPI 文档中的完整英文示例响应 （快照时间为 2026 年 8 月至 10 月）：

• list_sports、get_menu、top_matches：Live 和 Prematch；
• list_countries、list_live_matches、list_prematch_matches：足球（sport_id 1）；
• list_tournaments：足球，country_id 1；
• get_match：746146992（Live，Arsenal — Coventry City）和 730321837（Prematch，Manchester City — Bournemouth）；
• search_matches："Perth"（Live）和 "Manchester"（Prematch）。

其他请求（其他体育项目和比赛、日历、电子竞技、top_championships）都会返回一条消息，列出演示模式的覆盖范围以及获取密钥的方式。

更新间隔

每个响应都是一个快照。服务器会重复使用该快照，直到该方法文档中规定的最小间隔已过，例如 Live 比赛列表为 7 秒，Live 比赛为 5 秒，Prematch 比赛为 30 秒。从缓存提供的结果会包含 cached_seconds。对同一数据的并发调用会等待已在进行中的请求。请参阅数据更新指南。

文档

• 快速入门
• API 方法概览
• 核心概念：Live 与 Prematch、ID
• 错误处理
• 体育项目和 sport ID
• SportAPI 文档

想要自行构建集成？请使用本服务基于其构建的 SportAPI Python 客户端。

获取 API 密钥

Live 数据需要 SportAPI 提供的个人 API 密钥和基础 URL。套餐价格从每月 $30 起，并提供 2 天免费试用。

• Telegram： @sportapinet_bot
• 网站：sportapi.net

请将密钥保存在 MCP 客户端的配置或密钥存储中，切勿放在共享聊天或 Git 仓库中。

贡献

欢迎提交问题和拉取请求；请参阅 CONTRIBUTING.md。提交前请运行 ruff check . && mypy && pytest。

许可证

MIT © 2026 SportAPI