MLB Stats MCP Server

MLB Stats MCP サーバー

MLB Stats API と、Statcast、FanGraphs、Baseball Reference の統計データを取得するための pybaseball ライブラリを通じて、MLB の統計データにアクセスする Model Context Protocol（MCP）サーバーを作成する Python プロジェクトです。このサーバーは、MCP 対応クライアントで使用できる、野球統計データへの構造化された API アクセスを提供します。

プロジェクト構成

• mlb_stats_mcp/ - メインパッケージディレクトリ
  • server.py - MCP サーバーのコア実装
  • tools/ - MCP ツールの実装
    • mlb_statsapi_tools.py - MLB StatsAPI ツールの定義
    • statcast_tools.py - Statcast データツールの定義
    • pybaseball_plotting_tools.py - matplotlib プロットを生成し、Base64 エンコードされた画像を返すために用意された追加の pybaseball ツール
    • pybaseball_supp_tools.py - FanGraphs、Baseball Reference、その他のデータソースと連携するための pybaseball 補助関数
  • utils/ - ユーティリティモジュール
    • logging_config.py - ログ設定
    • images.py - プロット画像の処理に関連する関数
  • tests/ - サーバー機能を検証するテストスイート
• pyproject.toml - プロジェクトの設定と依存関係
• .pre-commit-config.yaml - pre-commit フックの設定
• .github/ - GitHub Actions ワークフロー

ツール

セットアップ

1. まだインストールしていない場合は、uv をインストールします。

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 仮想環境を作成して有効化します。

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

3. 依存関係をインストールします。

uv pip install -e .

Smithery 経由でのインストール

Smithery を使って、Claude Desktop 用の MLB Stats Server を自動的にインストールするには：

npx -y @smithery/cli install @etweisberg/mlb-mcp --client claude

テストの実行

このプロジェクトには、MCP サーバーの機能を検証するための包括的な pytest テストが含まれています。

uv run pytest -v

テストでは、すべての MLB StatsAPI ツールが MCP プロトコルで正しく動作し、接続の確立、API 呼び出し、レスポンスの処理が行われることを検証します。

環境変数

このプロジェクトでは、設定を構成するために .env に保存された環境変数を使用します。

MCP サーバーを有効にするには、ANTHROPIC_API_KEY を使用します。

ログ設定

MLB Stats MCP サーバーでは、環境変数を使ってログを設定できます。

• MLB_STATS_LOG_LEVEL - ログレベルを設定します（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• MLB_STATS_LOG_FILE - ログファイルのパス（設定されていない場合、ログは stderr に出力されます）

ログは意図的に stdout ではなく stderr に出力されます。stdio トランスポートでは、 stdout が JSON-RPC ストリームを担うため、そこに別の内容が出力されるとストリームが破損します。

HTTP トランスポート

python -m mlb_stats_mcp.server --http を使ってサーバーを HTTP 経由で実行します。サーバーは $PORT（デフォルトは 8081）でリッスンし、/mcp で MCP を提供します。

デフォルトでは、サーバーは任意の Host と任意の Origin を受け付けるため、リモート環境に そのままデプロイできます。制限するには、いずれかの変数にカンマ区切りのリストを設定します。

• MLB_STATS_ALLOWED_HOSTS - 受け付ける Host ヘッダーの値です。この変数を設定すると DNS リバインディング保護が有効になり、その他のホストへのリクエストは 421 で拒否されます。 エントリの末尾に :* を付けると、任意のポートを許可できます（例：localhost:*）。
• MLB_STATS_ALLOWED_ORIGINS - 受け付ける Origin の値です。CORS に使用されるほか、 MLB_STATS_ALLOWED_HOSTS が設定されている場合は、その他のオリジンを 403 で拒否するためにも使われます。 Origin ヘッダーのないリクエストは常に許可されます。

デプロイ環境を制限する場合は、両方を設定してください。ホストだけを指定すると、 ブラウザーをベースとするすべてのクライアントが拒否されます。

Claude Desktop との統合

この MCP サーバーを Claude Desktop に接続するには、claude_desktop_config.json ファイルに設定を追加します。設定テンプレートは次のとおりです。

"mcp-baseball-stats": {
  "command": "{PATH_TO_UV}",
  "args": [
    "--directory",
    "{PROJECT_DIRECTORY}",
    "run",
    "python",
    "-m",
    "mlb_stats_mcp.server"
  ],
  "env": {
    "MLB_STATS_LOG_FILE": "{LOG_FILE_PATH}",
    "MLB_STATS_LOG_LEVEL": "DEBUG"
  }
}

次のプレースホルダーを置き換えてください。

• {PATH_TO_UV}：uv のインストール先のパス（例：~/.local/bin/uv）
• {PROJECT_DIRECTORY}：プロジェクトディレクトリへのパス
• {LOG_FILE_PATH}：ログファイルの保存先のパス

使用技術

• mcp[cli] - ツール定義用の Machine-Learning Chat Protocol
• mlb-statsapi - MLB Stats API 用の Python ラッパー
• httpx - API リクエストを行うための HTTP クライアント
• pytest と pytest-asyncio - テストフレームワーク
• uv - 高速な Python パッケージマネージャーおよびインストーラー

リント

このプロジェクトでは、リントとコードフォーマットに Ruff を使用し、コード品質を確保するために pre-commit フックを導入しています。

Pre-commit フックの設定

1. pre-commit をインストールします。

pip install pre-commit

2. pre-commit フックを初期化します。

pre-commit install

これで、コードをコミットするたびにリントチェックが自動的に実行されます。手動で実行することもできます。

pre-commit run --all-files

リント設定

リントルールは、pyproject.toml ファイルの [tool.ruff] セクションで設定されています。このプロジェクトでは、いくつかのカスタマイズを加えた PEP 8 スタイルガイドラインに従っています。

CI との統合

GitHub Actions のワークフローでは、すべてのプルリクエストと main ブランチへのプッシュ時に、テスト、リント、pre-commit チェックが自動的に実行されます。