Pybaseball MCP Server

MLB Stats MCP Server

pybaseballライブラリを通じて、動画ハイライト付きのMLB野球統計を幅広く提供するModel Context Protocol（MCP）サーバーです。

概要

このMCPサーバーを使うと、AIアシスタントはMLBのリアルタイム統計、過去のデータ、動画ハイライトにアクセスできます。個々の選手の成績からチーム統計、Statcastの高度な指標まで、野球データを照会するための強力な8つのツールを提供します。

特長

🎯 8つの主要ツール

1. get_player_stats

日付を指定して、MLBの選手の詳細なStatcastデータを取得します。

• パラメーター：
  • name（必須）：選手名（例："Mike Trout"、"Ronald Acuña Jr."）
  • start_date（任意）：開始日（YYYY-MM-DD形式）
  • end_date（任意）：終了日（YYYY-MM-DD形式）
• **戻り値：**安打、本塁打、打球速度、打ち出し角度、バレル率などの選手統計

2. player_statcast

球種や結果を指定して、特定の選手の包括的なStatcastデータを取得します。

• パラメーター：
  • player_name（必須）：選手名（例："Aaron Judge"、"Mike Trout"）
  • start_date（任意）：開始日（YYYY-MM-DD形式。デフォルトは現在のシーズン）
  • end_date（任意）：終了日（YYYY-MM-DD形式。デフォルトは現在のシーズン）
  • pitch_type（任意）：球種で絞り込みます。'FF'（フォーシーム）、'SL'（スライダー）、'CH'（チェンジアップ）、'CU'（カーブ）、'SI'（シンカー）、'FC'（カッター）、'FS'（スプリッター）
  • result_type（任意）：結果で絞り込みます。'home_run'、'hit'、'single'、'double'、'triple'、'batted_ball'
  • min_exit_velocity（任意）：最低打球速度（mph）
  • min_distance（任意）：最小飛距離（フィート）
• **戻り値：**全体指標、球種／結果別の内訳、動画リンク付きの代表例上位5件を含む選手統計
• クエリ例：
  • 「Aaron Judgeは速球を何本本塁打にしていますか？」
  • 「Shohei Ohtaniのスライダーに対する平均打球速度はどのくらいですか？」
  • 「今シーズンのMike Troutの変化球に対する成績を見せてください」

3. get_team_stats

任意のシーズンについて、チームの打撃または投球統計を包括的に取得します。

• パラメーター：
  • team（必須）：チーム名または略称（例："Yankees"、"NYY"、"Red Sox"）
  • year（必須）：シーズンの年（1871年から現在まで）
  • stat_type（任意）："batting"（デフォルト）または"pitching"
• **戻り値：**指定したシーズンのチーム統計一式

4. get_leaderboard

MLBのあらゆる統計カテゴリのランキングを取得します。

• パラメーター：
  • stat（必須）：統計略称（例："HR"、"AVG"、"ERA"、"K"）
  • season（必須）：シーズンの年
  • leaderboard_type（任意）："batting"または"pitching"
  • limit（任意）：結果数（デフォルト：10）
• **戻り値：**指定した統計の上位選手

5. statcast_leaderboard

フィルタリング、並べ替え、動画ハイライトリンクを使って、高度な Statcast データをクエリします。

• パラメーター：
  • start_date（必須）：YYYY-MM-DD 形式の開始日
  • end_date（必須）：YYYY-MM-DD 形式の終了日
  • result（任意）：結果でフィルタリングします（例：「home_run」、「single」、「double」）
  • min_ev（任意）：打球速度の最小値でフィルタリングします
  • min_pitch_velo（任意）：投球速度の最小値でフィルタリングします
  • pitch_type（任意）：球種でフィルタリングします。「FF」（フォーシーム）、「SL」（スライダー）、「CH」（チェンジアップ）、「CU」（カーブ）、「SI」（シンカー）、「FC」（カッター）、「FS」（スプリッター）
  • player_name（任意）：打者名でフィルタリングします（例：「Aaron Judge」、「Mike Trout」）
  • sort_by（任意）：並べ替えの指標：
    • "exit_velocity"（デフォルト）- 打球速度が最も速い打球
    • "distance" - 飛距離が最も長い打球
    • "launch_angle" - 最適な打球角度
    • "pitch_velocity" - 投球速度が最も速い投球
    • "spin_rate" - 回転数が最も高い投球
    • "xba" - 期待打率が最も高い打球
    • "xwoba" - 期待加重出塁率が最も高い打球
    • "barrel" - バレル率（理想的なコンタクト）
  • limit（任意）：結果数（デフォルト：10）
  • order（任意）：並べ替え順。「desc」（デフォルト）または「asc」
  • group_by（任意）：チームごとのランキングを表示する場合は、結果を「team」でグループ化します
• 戻り値： 動画リンク付きの詳細なプレーごとのデータ（または、group_by="team"の場合はチーム別の集計）

6. team_season_stats

Statcast 指標のチーム別シーズン平均をすばやく取得します。「最も強い打球を打つチームは？」などのクエリに最適化されています。

• パラメーター：
  • year（必須）：シーズンの年（例：2025）
  • stat（任意）：分析する指標
    • "exit_velocity"（デフォルト）- 平均打球速度
    • "distance" - 平均および最大飛距離
    • "launch_angle" - 平均打球角度
    • "barrel_rate" - バレルの割合（理想的なコンタクト）
    • "hard_hit_rate" - 95 mph 以上で打たれた打球の割合
    • "sweet_spot_rate" - 最適な打球角度（8-32°）で打たれた打球の割合
  • min_result_type（任意）：結果の種類でフィルタリングします
    • "batted_ball" - インプレーになったすべての打球
    • "home_run" - ホームランのみ
    • "hit" - すべての安打（単打、二塁打、三塁打、ホームラン）
• 戻り値： 平均、件数、その他の統計を含むチームランキング
• パフォーマンス： サンプリング方式（7日ごと）と24時間キャッシュを使用し、即座に応答します

7. team_pitching_stats

Statcast 指標のチーム別投球平均をすばやく取得します。「最も優れた投手陣を擁するチームは？」などのクエリに最適化されています。

• パラメーター：
  • year（必須）：シーズンの年（例：2025）
  • stat（任意）：分析する指標
    • "velocity"（デフォルト）- 平均および最大投球速度
    • "spin_rate" - 平均および最大回転数
    • "movement" - 球の変化量（横方向、縦方向、合計）
    • "whiff_rate" - 空振り率
    • "chase_rate" - ストライクゾーン外の投球に対するスイング率
    • "zone_rate" - ストライクゾーン内に投げられた球の割合
    • "ground_ball_rate" - インプレーになった打球に対するゴロの割合
    • "xera" - コンタクトの質に基づく期待 ERA
  • pitch_type（任意）：特定の球種に絞り込みます
    • "FF" - フォーシーム・ファストボール
    • "SL" - スライダー
    • "CH" - チェンジアップ
    • "CU" - カーブ
    • "SI" - シンカー
    • "FC" - カッター
    • "FS" - スプリッター
• 戻り値： 平均、件数、その他の統計を含むチーム投球ランキング
• パフォーマンス： サンプリング方式（7日ごと）と24時間キャッシュを使用し、即座に応答します

8. statcast_count

特定の条件に一致するStatcastイベントをカウントします。「2023年以降、飛距離475フィート以上のホームランは何本？」のような複数年にわたるクエリに最適化されています。

• パラメーター：
  • start_date（必須）：YYYY-MM-DD形式の開始日
  • end_date（必須）：YYYY-MM-DD形式の終了日
  • result_type（任意）：カウントする種類。「home_run」（デフォルト）、「hit」、「batted_ball」、または「double」のような特定の種類
  • player_name（任意）：打者名で絞り込み（例：「Aaron Judge」、「Mike Trout」）
  • pitch_type（任意）：球種で絞り込み。「FF」（フォーシーム）、「SL」（スライダー）、「CH」（チェンジアップ）、「CU」（カーブ）、「SI」（シンカー）、「FC」（カッター）、「FS」（スプリッター）
  • min_distance（任意）：最小飛距離（フィート、例：475）
  • max_distance（任意）：最大飛距離（フィート）
  • min_exit_velocity（任意）：打球速度の最小値（mph）
  • max_exit_velocity（任意）：打球速度の最大値（mph）
• 戻り値： 合計数、年ごとの内訳、動画リンク付きの上位5件の例
• パフォーマンス：
  • 複数年にわたるクエリ：月あたり3日分をサンプリング（API呼び出しを約90分の1に削減）
  • 6～12か月：週単位でサンプリング（API呼び出しを約7分の1に削減）
  • 6か月未満：チャンク処理による全データの取得
  • すべてのクエリを24時間キャッシュ

🎥 動画ハイライトとの連携

statcast_leaderboardの各結果には、詳細な指標と動画へのアクセスポイントが含まれます。

{
  "rank": 1,
  "player": "Ronald Acuña Jr.",
  "date": "2024-07-20",
  "exit_velocity": 113.7,
  "launch_angle": 23.0,
  "distance": 456.0,
  "result": "home_run",
  "pitch_velocity": 95.2,
  "pitch_type": "FF",
  "spin_rate": 2450,
  "xba": 0.920,
  "xwoba": 1.823,
  "barrel": true,
  "description": "Ronald Acuña Jr. homers (13) on a fly ball to center field.",
  "video_links": {
    "game_highlights_url": "https://www.mlb.com/gameday/745890/video",
    "film_room_search": "https://www.mlb.com/video/search?q=Ronald+Acuna+Jr.+2024-07-20",
    "game_pk": "745890",
    "api_highlights_endpoint": "https://statsapi.mlb.com/api/v1/schedule?gamePk=745890&hydrate=game(content(highlights(highlights)))"
  }
}

🏟️ チーム名のスマート認識

サーバーはチーム名をインテリジェントに処理します。

• 正式名称：「Orioles」→「BAL」、「Red Sox」→「BOS」
• 都市名：「Boston」→「BOS」、「New York Yankees」→「NYY」
• 過去のチーム：「Expos」→「MON」、「Indians」→「CLE」
• 現在のMLB全30チームに、一般的な名称のバリエーションを含めて対応

📊 チーム全体のランキング

statcast_leaderboardに新しいチーム集計機能を追加しました。

• 結果をチーム別にグループ化し、チーム全体の成績を確認
• 各指標の平均値、最大値、件数を計算
• 「最も強いホームランを打つチームは？」のような質問に最適
• バレル数や期待値指標を含む、包括的なチーム統計を返します

インストール

Railwayでデプロイ（Smitheryでの利用に推奨）

Railwayにデプロイして、Smitheryが接続できるホスト型HTTP MCPエンドポイントを用意します。

1. 新しいRailwayプロジェクトを作成し、GitHubリポジトリに接続します
2. RailwayがProcfileを自動検出し、自動的にデプロイします
3. MCPエンドポイントはhttps://<your-railway-domain>/mcpで利用できます
4. このURLをSmitheryに接続して配布します

手動での起動コマンド（必要な場合）： RailwayがProcfileを自動検出しない場合は、Railwayの設定でこの起動コマンドを設定します。

uv run fastmcp run src/mlb_mcp/server.py:mcp --transport http --host 0.0.0.0 --port $PORT

Smithery Directでデプロイ

1. このリポジトリをフォークします
2. GitHubアカウントをSmitheryに接続します
3. リポジトリから直接デプロイします

ローカル開発

# Clone the repository
git clone https://github.com/yourusername/mlb_mcp.git
cd mlb_mcp

# Install dependencies with uv
uv sync

# Run the server (stdio mode for local testing)
uv run python -m mlb_mcp.server

# Or run with HTTP transport for local HTTP testing
MCP_TRANSPORT=http MCP_PORT=8000 uv run python -m mlb_mcp.server

Claude Desktopの設定

Claude Desktopの設定に追加します（stdioトランスポートを使用）。

{
  "mcpServers": {
    "mlb-stats": {
      "command": "uv",
      "args": ["run", "python", "-m", "mlb_mcp.server"],
      "cwd": "/path/to/mlb_mcp"
    }
  }
}

使用例

選手を指定したクエリ（新機能！）

Aaron Judgeは速球を何本ホームランにしていますか？

Query: "How many fastballs has Aaron Judge hit for a home run this season?"
Tool: player_statcast("Aaron Judge", "2024-04-01", "2024-10-31", "FF", "home_run")
OR
Tool: statcast_count("2024-04-01", "2024-10-31", "home_run", player_name="Aaron Judge", pitch_type="FF")

特定の球種に対する選手の成績は？

Query: "Show me Shohei Ohtani's stats against sliders this season"
Tool: player_statcast("Shohei Ohtani", "2024-04-01", "2024-10-31", "SL")

特定の球種に対する選手の最も強い打球

Query: "Show Aaron Judge's hardest hit balls on fastballs"
Tool: statcast_leaderboard("2024-04-01", "2024-10-31", player_name="Aaron Judge", pitch_type="FF", sort_by="exit_velocity", limit=10)

最長飛距離のホームランを検索

Query: "Show me the longest home runs from yesterday"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", "home_run", None, None, "distance", 10)

速球に対する最も強い打球

Query: "What were the hardest hit balls on 99+ mph pitches last week?"
Tool: statcast_leaderboard("2024-07-14", "2024-07-20", None, 0, 99.0, "exit_velocity", 10)

最速の投球

Query: "Show me the fastest pitches thrown yesterday"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "pitch_velocity", 10)

回転数が最も多い投球

Query: "What pitches had the highest spin rate today?"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "spin_rate", 10)

最も質の高いコンタクト（バレル）

Query: "Show me the best quality contact this week"
Tool: statcast_leaderboard("2024-07-14", "2024-07-20", None, None, None, "barrel", 10)

選手のシーズン成績

Query: "Get Mike Trout's stats for this season"
Tool: get_player_stats("Mike Trout", "2024-04-01", "2024-10-01")

チーム成績

Query: "How are the Red Sox doing this year?"
Tool: get_team_stats("Red Sox", 2024, "batting")

リーグの上位選手

Query: "Who's leading the league in home runs?"
Tool: get_leaderboard("HR", 2024, "batting", 10)

チーム全体のランキング（statcast_leaderboard）

Query: "Which team has the hardest hit home runs this season?"
Tool: statcast_leaderboard("2024-04-01", "2024-10-01", "home_run", None, None, "exit_velocity", 10, "desc", "team")

Query: "Show me teams with the longest average home run distance this month"
Tool: statcast_leaderboard("2024-07-01", "2024-07-31", "home_run", None, None, "distance", 10, "desc", "team")

Query: "Which teams have the highest average pitch velocity?"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "pitch_velocity", 10, "desc", "team")

チームのシーズン平均（team_season_stats）

Query: "What team averages the hardest hit balls in 2025?"
Tool: team_season_stats(2025, "exit_velocity")

Query: "Which team has the highest barrel rate this season?"
Tool: team_season_stats(2025, "barrel_rate")

Query: "Show me teams with the highest hard-hit rate on home runs only"
Tool: team_season_stats(2025, "hard_hit_rate", "home_run")

Query: "What team hits the ball the farthest on average?"
Tool: team_season_stats(2025, "distance")

チームの投球分析（team_pitching_stats）

Query: "Which team throws the hardest in 2025?"
Tool: team_pitching_stats(2025, "velocity")

Query: "What team has the best slider spin rate?"
Tool: team_pitching_stats(2025, "spin_rate", "SL")

Query: "Which pitching staff gets the most swings and misses?"
Tool: team_pitching_stats(2025, "whiff_rate")

Query: "Show me teams with the highest ground ball rate"
Tool: team_pitching_stats(2025, "ground_ball_rate")

Query: "Which team has the lowest expected ERA based on contact quality?"
Tool: team_pitching_stats(2025, "xera")

件数を数えるクエリ（statcast_count）

Query: "How many home runs hit over 475 ft have been hit since 2023?"
Tool: statcast_count("2023-01-01", "2025-12-31", "home_run", 475)

Query: "Count all 110+ mph batted balls this season"
Tool: statcast_count("2025-04-01", "2025-10-31", "batted_ball", None, 110)

Query: "How many home runs between 400-450 feet were hit last year?"
Tool: statcast_count("2024-04-01", "2024-10-31", "home_run", 400, None, 450)

Query: "Total hits with exit velocity over 100 mph since 2022"
Tool: statcast_count("2022-01-01", "2025-12-31", "hit", None, 100)

技術詳細

アーキテクチャ

• トランスポート：stdio（ローカル）または HTTP（Railway／ホスト型）。PORT 環境変数によって自動検出されます
• フレームワーク：プロトコルの実装に FastMCP を使用
• データソース：pybaseball ライブラリ（MLB 公式データ）
• 言語：Python 3.11 以降
• デプロイ：Railway（HTTP）または Smithery（コンテナ化）

パフォーマンスの最適化

• クエリの分割：大きな日付範囲を自動的に 5 日間のチャンクに分割し、Baseball Savant の 30,000 行制限に対応します
• レスポンスのキャッシュ：クエリの繰り返しには 15 分間、チームのシーズン統計には 24 時間のキャッシュを使用します
• ベクトル化された処理：処理速度の遅い pandas の apply() 操作の代わりに NumPy を使用して、チームを効率よく識別します
• サンプリング戦略：
  • team_season_stats と team_pitching_stats：7 日ごとにサンプリングします
  • statcast_count：適応型サンプリング（複数年の場合は月に 3 日、6～12 か月の場合は週ごと）
• 専用ツール：全データを使用するとタイムアウトする一般的な集計クエリに対応する専用ツール：
  • 打撃指標用の team_season_stats
  • 投球指標用の team_pitching_stats
  • 複数年にわたる件数クエリ用の statcast_count
• 遅延読み込み：起動を高速化するため、pandas、numpy、pybaseball などの重量級依存関係は必要になったときにのみ読み込みます
• 効率的なフィルタリング：データ処理のオーバーヘッドを最小限に抑えるため、フィルターを順番に適用します

主な機能

• エラー処理：よくある問題に対して、包括的なエラーメッセージを表示します
• 型安全性：JSON シリアライズに適した型変換を行います
• 動画連携：すべてのプレーとチームのトップパフォーマンスに、動画ハイライトへのリンクを自動で追加します
• スマートなチーム検索：正式名称、略称、都市名、過去のチーム名に対応します

ファイル構成

mlb_mcp/
├── src/
│   └── mlb_mcp/
│       ├── __init__.py    # Package exports
│       └── server.py      # Main MCP server implementation
├── pyproject.toml         # Project configuration and dependencies
├── smithery.yaml          # Smithery deployment configuration
├── Procfile               # Railway start command
└── README.md              # This file

要件

• Python 3.11 以降
• MLB データにアクセスするためのインターネット接続
• デプロイ用の Smithery アカウント（任意）

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。

ライセンス

このプロジェクトでは、pybaseball ライブラリを通じて公開されている MLB データを使用します。すべての MLB データは MLB Advanced Media の所有物です。

---

使用技術： pybaseball と FastMCP