espn

🏈 mcp-server-espn

企业级 Model Context Protocol（MCP）服务，用于通过 ESPN 获取实时和历史体育数据分析、共识投注赔率及预测。
为 AI Agent 提供实时体育情报、实时胜率预测、深入的记分统计、阵容层级信息和对阵分析。

⚠️ 免责声明与合理使用声明

重要

社区项目免责声明
mcp-server-espn 是一个独立的开源社区项目，与 ESPN Inc. 或 The Walt Disney Company 没有任何关联，也未获得其赞助、认可或支持。“ESPN” 是 ESPN Inc. 的商标。通过 ESPN 公开 REST 接口提供的所有数据，旨在用于教育、研究和个人非商业用途。

💡 项目缘起

自主体育分析需要高速、结构化且可靠的数据流：

1. 实时比赛状态与获胜概率： 实时比赛事件（失误、得分进攻、投手更换）会动态改变比赛势头和预期结果。
2. 关键球员伤情与阵容深度调整： 比赛中的受伤或换人会从根本上改变球队效率和战术对阵。
3. 共识赔率与预测模型： 汇总体育博彩公司的共识赔率（DraftKings、Caesars、ESPN BET）以及预测指标（FPI、BPI），可用于深入评估比赛数据。

mcp-server-espn 提供统一且经过加固的 Model Context Protocol 接口，直接连接 ESPN 的公开体育数据接口。

🏟️ 系统架构

graph TD
    Client["AI Agent / MCP Client<br>(Antigravity, Claude, Codex, Cortex)"]
    Gateway["Root FastMCP Gateway (espn-mcp)<br>(stdio / Streamable HTTP)"]
    ParentMW["Parent Middleware Pipeline<br>(ParentAuditMiddleware & ReadOnlyGateMiddleware)"]
    GamesSub["Sub-Server: espn-games<br>(games_* | GamesDomainGuard)"]
    TeamsSub["Sub-Server: espn-teams<br>(teams_* | TeamsDomainGuard)"]
    NewsSub["Sub-Server: espn-news<br>(news_* | Resources)"]
    ClientHandler["Hardened ESPN AsyncClient<br>(Connection Pool & 429 Jitter Backoff)"]
    ESPN["ESPN Public REST CDN<br>(https://site.web.api.espn.com)"]

    Client <-->|"JSON-RPC (tools/list, tools/call)"| Gateway
    Gateway --> ParentMW
    ParentMW --> GamesSub
    ParentMW --> TeamsSub
    ParentMW --> NewsSub
    GamesSub & TeamsSub & NewsSub <-->|"API Methods"| ClientHandler
    ClientHandler <-->|"HTTPS REST Mirror"| ESPN

🚀 FastMCP 4 服务组合

mcp-server-espn 通过 root.mount(..., namespace="...") 实现规范的 FastMCP 4 服务组合：

• 领域子服务：划分为 espn-games（games_*）、espn-teams（teams_*）和 espn-news（news_*）。
• 分层中间件：
  • 父级：ParentAuditMiddleware（计时日志、审计跟踪和敏感信息清理）以及 ReadOnlyGateMiddleware（失败时默认拒绝的只读强制机制）。
  • 子级：GamesDomainGuardMiddleware（查询限制验证，<= 100）和 TeamsDomainGuardMiddleware（球队和运动员标识符验证）。
• 专用配置：通过 --profile full|games|teams|news|readonly（ESPN_MCP_PROFILE）运行轻量级功能集：
  • full（默认）：挂载全部 33 个领域工具和资源。
  • games：比分、摘要、赛程、排名、排行榜、交易、联盟领跑者、选秀、实时比赛逐球记录、比赛情况、赔率、概率、预测器、日历、未来赛果和实力指数（20 个工具）。
  • teams：阵容、深度图、球员数据、运动员档案、简介、数据、比赛记录、分类统计、搜索、球队列表、球队详情、球队数据（12 个工具）。
  • news：联盟新闻和参考资源（1 个工具）。
  • readonly：对所有路由强制执行只读限制。
• 选择启用工具搜索：默认保留标准的扁平 tools/list，确保与客户端无缝兼容；同时可通过 --enable-tool-search（ESPN_MCP_ENABLE_TOOL_SEARCH）启用搜索转换：默认使用 BM25 对自然语言查询进行排序（search_tools 接受 query），也可通过 --tool-search-backend regex（ESPN_MCP_TOOL_SEARCH_BACKEND=regex；search_tools 接受 pattern）使用正则表达式模式。

📈 体育智能工作流

工作流 1：实时比赛胜率与比赛情况跟踪

1. 轮询正在进行的比赛： Agent 调用 games_get_scoreboard(sport="football", league="nfl")，找出下半场比分接近的比赛。
2. 获取比赛情况与胜率： 调用 games_get_game_situation(sport="football", league="nfl", event_id="401872947") 和 games_get_win_probabilities(sport="football", league="nfl", event_id="401872947")，查看进攻档数／码数、红区状态和实时胜率曲线。
3. 查看逐球记录： 调用 games_get_play_by_play(sport="football", league="nfl", event_id="401872947")，获取逐个进攻回合的比赛进程和得分事件记录。

工作流 2：深入分析运动员与梦幻体育估值

1. 简介与职业生涯背景： 调用 teams_get_athlete_bio(sport="football", league="nfl", athlete_id="12483")，获取选秀顺位、大学经历和身体指标。
2. 近期比赛记录与分类统计： 调用 teams_get_athlete_gamelog 和 teams_get_athlete_splits，分析球员面对特定防守战术和场馆条件时的表现趋势。
3. 联盟整体排行榜排名： 调用 games_get_leaders_by_athlete(sport="football", league="nfl", category="passing", sort="yards")，评估百分位排名。

🏟️ 支持的体育项目与联赛参考表

服务支持规范的体育项目 / 联赛 slug 配对，并会自动规范化常见简称：

📊 工具套件（33 个领域工具）

所有工具均实现了明确的 MCP 2.0 注解（readOnlyHint=True、idempotentHint=True）：

🏃 快速开始与安装

1. 通过 uvx 直接运行（无需安装）

[project.scripts] 中的控制台脚本都会调用 espn_mcp.server:main：espn-mcp（下文使用）和 mcp-server-espn。安装示例不会固定版本。若要锁定某个版本，请选择 Releases 中的版本。

uvx --from mcp-server-espn espn-mcp

升级后，请重新加载 MCP 宿主，确保运行中进程的启动时间晚于新二进制文件的修改时间（旧进程 ≠ 新软件包）。

2. 通过 pip 或 uv 安装

# Using pip
pip install mcp-server-espn

# Using uv
uv add mcp-server-espn

3. 通过 Docker 运行

docker run --rm -i ghcr.io/christianclaudio/mcp-server-espn:latest

🎛️ 引擎配置

🎮 客户端集成指南

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["--from", "mcp-server-espn", "espn-mcp"],
      "env": {
        "ESPN_TIMEOUT_SECONDS": "20.0"
      }
    }
  }
}

claude mcp add espn -- uvx --from mcp-server-espn espn-mcp

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["--from", "mcp-server-espn", "espn-mcp"],
      "env": {
        "ESPN_TIMEOUT_SECONDS": "20.0"
      },
      "lazy": true
    }
  }
}

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["--from", "mcp-server-espn", "espn-mcp"],
      "env": {
        "ESPN_TIMEOUT_SECONDS": "20.0"
      },
      "lazy": true
    }
  }
}

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["--from", "mcp-server-espn", "espn-mcp"]
    }
  }
}

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["--from", "mcp-server-espn", "espn-mcp"]
    }
  }
}

uvx --from mcp-server-espn espn-mcp --transport streamable-http --host 127.0.0.1 --port 8000

PUBLIC_HOST=mcp.example.com   # the host name clients use
export ESPN_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"   # or keep it in an env file
docker run --rm -p 8000:8000 -e ESPN_MCP_AUTH_TOKEN \
  ghcr.io/christianclaudio/mcp-server-espn:latest \
  --transport streamable-http --host 0.0.0.0 --allowed-host "$PUBLIC_HOST"
# with an env file instead: docker run --rm -p 8000:8000 --env-file espn.env ...

📚 权威文档与实时文档 MCP 服务

开发、加固或扩展 MCP 服务时，请查阅官方框架和协议参考资料：

• FastMCP 4 框架参考：https://gofastmcp.com/llms.txt — 服务组合（mount）、分层中间件、转换（ToolTransform、ToolSearch）、生命周期以及内存中的测试客户端。
• Model Context Protocol 规范：https://modelcontextprotocol.io/llms.txt — 官方规范（2026-07-28）、线路级 JSON-RPC 架构、注解和传输帧格式。

实时文档 MCP 端点（SSE / Streamable HTTP）

将 AI 编码 Agent 直接连接到实时文档服务：

• FastMCP 文档服务：https://gofastmcp.com/mcp（工具：search_fast_mcp、query_docs_filesystem_fast_mcp、submit_feedback）
• Anthropic MCP 文档服务：https://modelcontextprotocol.io/mcp（工具：search_model_context_protocol、query_docs_filesystem_model_context_protocol、submit_feedback）

{
  "mcpServers": {
    "fastmcp-docs": { "type": "sse", "url": "https://gofastmcp.com/mcp" },
    "mcp-official-docs": { "type": "sse", "url": "https://modelcontextprotocol.io/mcp" }
  }
}

🏆 验证与质量门禁

# Run unit test suite (100% statement coverage enforced)
pytest

# Static type safety & formatting
mypy --strict src/
ruff check --fix .
ruff format .

# Tool contract, drift & protocol conformance audits
python scripts/check_tool_contract.py
python scripts/check_openapi_drift.py
./scripts/check_conformance.sh

📜 许可证

基于 Apache-2.0 License 发布。