sports-mcp-server

---

概览

来自 ESPN、MLB StatsAPI 和 TheSportsDB 的实时及历史体育数据。查询 NFL、NBA、MLB、NHL、主要足球联赛以及大学橄榄球和篮球的比分、赛程和排名，并查找球队和球员信息。

工具

工具	说明
sports_find_team	跨数据提供方，将球队名称或部分名称解析为规范记录和来源 ID。
sports_find_player	将球员姓名解析为 TheSportsDB 规范记录，包含 ID、球队、位置和简介字段。
sports_get_scores	查询指定日期某个联赛的实时和最终比分，可按球队筛选。
sports_get_game	比赛元数据、各节比分、球队总计、数据提供方的表现最佳球员，以及分页的得分回合。
sports_get_schedule	查询指定日期范围内某支球队或某个联赛的即将举行和已结束的比赛。
sports_get_standings	查询某个联赛和赛季的当前排名或联赛积分榜。
sports_get_team	汇总球队元数据、阵容、近期赛果和即将举行的比赛，提供球队详情。
sports_get_player	获取 TheSportsDB 中的球员详情——简介、球队、位置和身体数据。

功能参考

sports_find_team _工具

• 接受自由文本 query（最多 200 个字符），并可选用 league 筛选
• 返回跨数据提供方合并的球队元数据，包含 espnId/mlbId/tsdbId 交叉引用；totalFound 统计返回的记录数
• ESPN/MLB 查询失败时会列于 unavailableSources；无结果时返回 no_match，若某个数据来源查询失败则返回 sources_unavailable。免费的 TheSportsDB 密钥可能返回不完整结果

---

sports_find_player _工具

• 自由文本 query（最多 200 个字符）；可选的 sport 仅供参考，不会用于筛选
• 返回球员 ID、姓名、球队、位置、国籍、出生日期和缩略图；未找到时返回 no_match
• 默认键 3 会将搜索结果限制为一条记录

---

sports_get_scores _工具

• 必填 league；date（YYYY-MM-DD）默认为美国东部时间的当天；可选的 team_name 用于筛选比赛
• 返回主客队、比分、状态、节次或计时，以及 UTC 开始时间。无结果时会附带 reason、emptyReason（no_games 或 no_team_matches）和 notice
• limit 默认为 100（最大 200），offset 默认为 0；响应包含 availableGames、totalReturned、effectiveLimit、offset、truncated 和 nextOffset

---

sports_get_schedule _工具

• 必填 league；可选的 team_name、date_from/date_to、limit（默认 100，最大 200）和 offset（默认 0）。仅指定一个日期边界时会查询当天；日期范围颠倒时请求会失败
• 返回主客队和比分、状态、UTC 开始时间、场馆和来源。部分匹配的 team_name 必须能唯一确定一支球队：ambiguous_team 会列出候选项，team_not_found 表示没有匹配结果
• 按日期查询时，范围最多为七天。响应包含 requestedDateFrom/requestedDateTo、servedDateFrom/servedDateTo、availableGames、effectiveLimit、offset 和 truncated；请使用 nextOffset，然后将 nextDateFrom 作为 date_from

---

sports_get_game _工具

• 必填 league 和带来源前缀的数字 game_id，该 ID 来自比分、赛程或球队详情；mlb: ID 必须搭配 league: "mlb"
• 返回比赛元数据以及 periodScores、teamStats、leaders 和 scoringPlays；缺失值为 null。已安排的比赛仅返回元数据；比赛不存在或联赛不匹配时返回 game_not_found。运动员 ID 属于 ESPN 或 MLB，而非 TheSportsDB
• limit 默认为 20（最大 50），offset 默认为 0；响应包含 totalCount、returnedCount、servedFrom/servedTo、effectiveLimit 和 nextOffset

---

sports_get_standings _工具

• 必填 league；可选的 season（4 位数年份），省略时使用当前赛季
• 返回排名、分组（联盟分区、积分榜分组或 MLB 分区）、胜场、负场、平局、NHL 加时赛负场、积分、胜率、分区排名、连胜连败情况和落后场次；不适用的值为 null。该赛季没有数据时返回 season_not_found
• limit 默认为 100（最大 200），offset 默认为 0；响应包含 availableStandings、totalReturned、effectiveLimit、offset、truncated 和 nextOffset。如果 MLB 球队查询失败，unavailableSources 会列出 standings_team_metadata

---

sports_get_team _工具

• 必填 league 和 team_name；优先匹配全名或缩写，否则部分名称必须能唯一确定一支球队（ambiguous_team 会列出候选项，team_not_found 表示没有匹配结果）
• 返回元数据、现役阵容、最近 5 场已结束的比赛结果，以及接下来 3 场已安排的比赛
• NFL 阵容不包含伤病预备名单/缺阵、停赛和训练阵容中的球员；缺失的球衣号码和场馆信息为 null

---

sports_get_player _工具

• player_id 可接受带 tsdb: 前缀的 ID（来自 sports_find_player），或原始数字格式的 TheSportsDB ID
• 返回个人简介、球队、位置、国籍、出生日期、身高、体重和缩略图；ID 无法解析时返回 player_not_found
• TheSportsDB 提供 espnId 时会填入，否则为 null

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

体育专属功能：

• 三个无需密钥的数据源——ESPN 站点 API、MLB StatsAPI 和 TheSportsDB（免费层密钥 3）
• 联赛路由会根据运动项目将每个查询发送到最合适的数据源
• 各数据源采用统一的输出类型——NormalizedGame、NormalizedTeam、NormalizedPlayer、NormalizedStanding
• sports_find_team 会将来自不同数据源的球队 ID 合并到同一条记录中
• 休赛期查询会返回提示（排名），或返回带有 reason 的 games: []（比分板），而不是报错

便于 Agent 使用的输出：

• 每条记录都包含数据来源信息——source: 'espn' | 'mlbstats' | 'thesportsdb'
• 提供类型化的错误原因（no_match、sources_unavailable、team_not_found、ambiguous_team、player_not_found、season_not_found、game_not_found、incompatible_game_source），每种原因都附带恢复提示
• 每个响应都包含类型化的空结果提示，以及分页或赛程窗口元数据
• 对提供方文本进行转义并将其视为数据，而非指令

开始使用

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "sports": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/sports-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "sports": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/sports-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "sports": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/sports-mcp-server:latest"
      ]
    }
  }
}

要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥——ESPN 和 MLB StatsAPI 完全无需密钥；TheSportsDB 附带免费的公开测试密钥（3）。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/sports-mcp-server.git

2. 进入目录：

cd sports-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env to override defaults (all optional)

配置

变量	说明	默认值
THESPORTSDB_API_KEY	TheSportsDB API 密钥。免费密钥的搜索结果仅限一条记录。	3
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateful、stateless 或 auto。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录失败的工具参数和结果；按键名进行脱敏，并受 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 限制（默认值为 16384）。自由格式的值不会脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于跟踪和指标的 OTLP/HTTP 基础 URL。	未设置
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP 日志端点。	未设置

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

服务命令会执行 Node，包括通过 bun run 启动时也是如此。Bun 负责依赖解析和构建工具；ESPN 请求则由 Node 处理。

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t sports-mcp-server .
docker run --rm -p 3010:3010 sports-mcp-server

Dockerfile 使用 Bun 构建，在 Node 下运行生产服务，默认采用 HTTP 传输和无状态会话模式，并将日志写入 /var/log/sports-mcp-server。默认会安装 OpenTelemetry 对等依赖项——使用 --build-arg OTEL_ENABLED=false 构建即可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具并初始化服务。
src/config	解析服务专用环境变量（THESPORTSDB_API_KEY）。
src/services/types.ts	规范化的跨来源类型和联赛路由表。
src/services/espn	ESPN 站点 API 服务 — 赛果、赛程、排名、球队。
src/services/mlb	MLB StatsAPI 服务 — 赛果、赛程、排名、阵容。
src/services/thesportsdb	TheSportsDB 服务 — 球员和球队搜索／元数据。
src/mcp-server/tools	工具定义（*.tool.ts）。
tests/	与 src/ 结构对应的单元测试和集成测试。
docs/	设计文档和目录树。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要说明：

• 处理程序抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 通过 src/mcp-server/tools/definitions/index.ts 中的 barrel 文件注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。