espn

🏈 mcp-server-espn

ESPNを通じて、ライブおよび過去のスポーツ分析、コンセンサスベッティングオッズ、予測を提供するエンタープライズグレードのModel Context Protocol（MCP）サーバーです。
AIエージェントに、リアルタイムのスポーツ情報、ライブ勝率、詳細なボックススコア統計、ロースターの階層構造、対戦分析を提供します。

⚠️ 免責事項と公正利用に関するお知らせ

重要

コミュニティプロジェクトに関する免責事項
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は、ESPNの公開スポーツデータエンドポイントに直接接続する、統一された堅牢なModel Context Protocolインターフェースを提供します。

🏟️ システムアーキテクチャ

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. 進行中の試合を確認：エージェントが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")を呼び出し、パーセンタイル順位を評価します。

🏟️ 対応スポーツ・リーグの参照一覧

サーバーは正規のスポーツ／リーグのスラッグペアに対応しており、よく使われるショートカットは自動的に正規化されます。

📊 ツールスイート（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

アップグレード後は、稼働中のプロセスの起動時刻が新しいバイナリの mtime より後になるよう、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 コーディングエージェントをライブドキュメントサーバーに直接接続できます。

• 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 の下で配布されています。