sports-mcp-server

---

概要

ESPN、MLB StatsAPI、TheSportsDB から、スポーツのライブデータと過去データを取得します。NFL、NBA、MLB、NHL、主要なサッカーリーグ、カレッジフットボールおよびバスケットボールのスコア、試合日程、順位表を確認したり、チームや選手を検索したりできます。

ツール

ツール	説明
sports_find_team	チーム名または部分一致する名前から、各プロバイダーの正規化されたレコードとソース ID を特定します。
sports_find_player	選手名から、ID、チーム、ポジション、プロフィール項目を含む TheSportsDB の正規化されたレコードを特定します。
sports_get_scores	指定日のリーグのライブスコアと試合終了スコアを取得します。チームで絞り込むこともできます。
sports_get_game	試合のメタデータ、ピリオドごとのスコア、チーム合計、プロバイダーが選ぶ注目選手、ページ分割された得点プレーを取得します。
sports_get_schedule	日付範囲を指定して、チームまたはリーグの今後および過去の試合日程を取得します。
sports_get_standings	リーグとシーズンを指定して、現在の順位表またはリーグ表を取得します。
sports_get_team	メタデータ、ロースター、最近の試合結果、今後の試合日程をまとめたチームの詳細情報を取得します。
sports_get_player	TheSportsDB から選手の詳細情報（プロフィール、チーム、ポジション、身体データ）を取得します。

機能リファレンス

sports_find_team _ツール

• 任意の league フィルターを指定できる自由記述の query（最大 200 文字）
• 各プロバイダーの相互参照情報を統合したチームのメタデータを返します。espnId／mlbId／tsdbId が含まれます。totalFound は返されたレコード数です。
• ESPN／MLB の検索に失敗した場合は unavailableSources に表示されます。結果がない場合は no_match を返し、ソースでエラーが発生した場合は sources_unavailable を返します。無料の TheSportsDB キーでは、結果が不完全になる場合があります。

---

sports_find_player _tool

• 自由記述の query（最大200文字）。任意の sport は参考情報であり、絞り込みには使用されません
• 選手ID、名前、チーム、ポジション、国籍、生年月日、サムネイルを返します。見つからない場合は no_match を返します
• デフォルトキー 3 は検索結果を1件に制限します

---

sports_get_scores _tool

• 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 _tool

• league は必須です。任意で team_name、date_from／date_to、limit（デフォルト100、最大200）、offset（デフォルト0）を指定できます。日付の境界を1つだけ指定するとその日の予定を取得します。日付の順序が逆の場合はエラーになります
• ホーム／アウェイチームとスコア、ステータス、UTCの開始時刻、会場、情報源を返します。部分一致の team_name でチームを1つに特定できる必要があります。ambiguous_team は候補を一覧表示し、team_not_found は一致するチームがないことを示します
• 日付を指定したリクエストで取得できる期間は最大7日です。レスポンスには requestedDateFrom／requestedDateTo、servedDateFrom／servedDateTo、availableGames、effectiveLimit、offset、truncated が含まれます。nextOffset に続いて、nextDateFrom を date_from として指定します

---

sports_get_game _tool

• league と、スコア、スケジュール、またはチーム詳細から取得した、情報源の接頭辞付き数値 game_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 _tool

• 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 _tool

• league と team_name は必須です。完全一致する名前または略称が優先されます。それ以外の場合は、部分一致の名前でチームを1つに特定できる必要があります（ambiguous_team は候補を一覧表示し、team_not_found は一致するチームがないことを示します）
• メタデータ、現役選手名簿、直近の終了済み試合結果5件、次の予定試合3件を返します
• NFLの選手名簿には、故障者リザーブ／登録外、出場停止、練習チームの選手は含まれません。背番号と会場が不明な場合はnullです

---

sports_get_player _tool

• player_id には、sports_find_player から取得した tsdb: 接頭辞付きID、または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 トレーシング（任意）に対応した構造化ログを提供します。

スポーツ固有の機能：

• API キー不要のデータソースが 3 つあります — ESPN サイト API、MLB StatsAPI、TheSportsDB（無料枠のキー 3）
• リーグの振り分けにより、スポーツごとに最適なデータソースへ各クエリを送信します
• データソース間で正規化された出力型 — NormalizedGame、NormalizedTeam、NormalizedPlayer、NormalizedStanding
• sports_find_team により、異なるデータソースのチーム ID を 1 つのレコードに統合します
• オフシーズンのクエリでは、エラーではなく通知（順位表）または reason を含む games: []（スコアボード）を返します

エージェントに適した出力：

• すべてのレコードにデータソースの由来を含めます — 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 キーです。無料キーでは検索結果が 1 件に制限されます。	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 を参照してください。

サーバーの実行

ローカル開発

サービング用のコマンドは、bun run で起動した場合も含め、Node を実行します。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 のバレルを介して新しいツールを登録します。
• 外部 API 呼び出しは、受信したデータを検証し、ドメイン型に正規化してから、出力スキーマに沿って返します。不足しているフィールドを捏造しないでください。

貢献

イシューを歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。