MCP Sport

MCP Sport — F1 テレメトリー MCP 🏎️

OpenF1 API の Formula 1 データを、AI アシスタント （Claude Desktop、Cursor、MCP Inspector など）向けのツールとして提供する MCP（Model Context Protocol） サーバーです。

全機能を網羅：ドキュメント化された OpenF1 エンドポイント 18 個に対応する 18 個のデータツールを提供します。対象はセッション、ミーティング、ドライバー、結果、ラップ、ピットストップ、スティント、テレメトリー、天候、選手権などです。このデータを使った MCP App ビューが 2 つあり、ドライバーの順位表とアニメーション付きレースリプレイを表示します。MCP Apps をレンダリングするホストでは HTML が表示されます。Cursor と Claude Desktop は対応しておらず、同じ内容が JSON として返されます。

技術スタック

レイヤー	技術
言語	Python 3.13+
MCP フレームワーク	FastMCP 4.x
検証	Pydantic v2
データ	OpenF1 API（REST、2023 年以降の過去データは無料）
プロジェクト管理	uv + pyproject.toml
トランスポート	stdio

インストール

# Clone and install dependencies
git clone https://github.com/andrequeiroz2/mcp-sport.git mcp-sport
cd mcp-sport
uv sync

使い方

サーバーを起動する（stdio）

.venv/bin/python src/mcp_sport/server.py

MCP Inspector（ツールをテストする Web UI）

npx @modelcontextprotocol/inspector@latest .venv/bin/python src/mcp_sport/server.py

Inspector UI で、トランスポートに STDIO、コマンドに .venv/bin/python、 引数に src/mcp_sport/server.py を指定し、Connect をクリックします。

Claude Desktop / Cursor

クライアントの MCP 設定に追加します。

{
  "mcpServers": {
    "f1-telemetry": {
      "command": "/absolute/path/mcp-sport/.venv/bin/python",
      "args": ["/absolute/path/mcp-sport/src/mcp_sport/server.py"]
    }
  }
}

18 個のデータツールはどちらのクライアントでも動作します。ビューは表示されません。

ビュー（MCP Apps）

get_drivers_championship_view と get_race_replay_view は、インタラクティブな HTML を返します。Cursor と Claude Desktop は MCP Apps に対応していません。UI を無視して JSON ペイロードを表示します。MCP Inspector も結果をテキストとして扱います。

ビューは、modelcontextprotocol/ext-apps の公式 basic-host で検証されています。サーバーは HTTP で起動し、MCP セッションヘッダーを公開する CORS を設定する必要があります。 そうしないと、ブラウザーは Streamable HTTP ハンドシェイクを完了できません。

ターミナル 1 — ポート 8765 で MCP サーバーを起動します。

uv run python -c "
import uvicorn
from starlette.middleware import Middleware
from starlette.middleware.cors import CORSMiddleware
from mcp_sport.server import mcp

app = mcp.http_app(middleware=[Middleware(
    CORSMiddleware,
    allow_origins=['*'],
    allow_methods=['*'],
    allow_headers=['*'],
    expose_headers=['mcp-session-id', 'mcp-protocol-version'],
)])
uvicorn.run(app, host='127.0.0.1', port=8765)
"

ターミナル 2 — basic-host（Node.js が必要です。npm start には bun が必要なため、tsx を使用します）。

git clone --depth 1 https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps/examples/basic-host
npm install
npm run build
SERVERS='["http://127.0.0.1:8765/mcp"]' npx tsx serve.ts

http://localhost:8080（サンドボックスは :8081）を開き、get_drivers_championship_view または get_race_replay_view を呼び出します。ビューの HTML を変更した後は、ツールを再度実行する前にページをハードリフレッシュ（Ctrl+Shift+R）してください。ホストは ui:// リソースをキャッシュします。

利用可能なツール（18 個）

ドメイン	ツール	説明
ナビゲーション	get_sessions	セッション（フリー走行、予選、スプリント、レース）
	get_meetings	グランプリとテストの週末
登録情報	get_drivers	セッション／ミーティングごとのドライバー
結果	get_session_results	セッションの最終順位
	get_starting_grid	スターティンググリッド
	get_positions	セッション中の順位履歴
レース	get_laps	ラップタイム、セクター、速度
	get_pit_stops	ピットストップ
	get_stints	スティントとタイヤコンパウンド
	get_intervals	リアルタイムのギャップ（リーダーと前のマシン）
	get_race_control	フラッグ、セーフティカー、インシデント
コンテキスト	get_weather	サーキットの天候（1 分ごとのサンプル）
	get_overtakes	オーバーテイク
	get_team_radio	チームラジオの抜粋（MP3）
テレメトリー	get_car_data	速度、RPM、ギア、スロットル、ブレーキ、DRS（約 3.7 Hz）
	get_location	サーキット上のおおよそのマシン位置（約 3.7 Hz）
選手権	get_drivers_championship	ドライバー順位（ベータ版）
	get_teams_championship	チーム順位（ベータ版）

AI との会話例

「ノリスは直近 2 レースで何ポイント獲得しましたか？」

AI は次のように処理します。最近のセッションを見つけるために get_sessions(session_type="Race") を実行し、各セッションで get_session_results(session_key=..., driver_number=4) を実行します。

プロジェクト構成

src/mcp_sport/
├── server.py           # Entrypoint: FastMCP instance + tool registration
├── exceptions.py       # Domain exceptions
├── logging_config.py   # Logging to stderr (stdout is the protocol channel)
├── clients/openf1.py   # Single OpenF1 HTTP client
├── schemas/            # Pydantic: input (BaseInput) and output per endpoint
├── validators/         # Business validations per endpoint
├── services/           # Orchestration per endpoint
├── tools/              # MCP tools (thin layer) per endpoint
└── apps/               # MCP App views (Custom HTML, ui:// resource)
    ├── championship_view.py  # Drivers standings board
    └── race_replay_view.py   # Animated race replay

正式なドキュメント

ドキュメント	内容
docs/Technical_Reference.md	技術スタック、バージョン、公式リンク（信頼できる情報源）
docs/Architectural_Design.md	実装パターンと新しいエンドポイントの手順
docs/Logging_Strategy.md	ロギング戦略（stderr ＋ リクエストごとのテレメトリー）
tasks/	計画・実行済みタスクの履歴

設定

変数	デフォルト	説明
MCP_SPORT_LOG_LEVEL	INFO	stderr に出力するログレベル（DEBUG、INFO、WARNING、ERROR）

既知の制限事項

• 2023 年以降の過去データを利用できます。リアルタイムデータには、有料の OpenF1 サブスクリプションが必要です
• session_result と starting_grid は、公式結果が公開されるまで HTTP 404 を返します
• テレメトリー（car_data、location）は、セッション／ドライバーごとに 18～24k 件のサンプルを返します。 speed_min や date_from／date_to などの範囲フィルターを使って、呼び出し対象を絞り込んでください
• OpenF1 のチャンピオンシップ用エンドポイントはベータ版です

ライセンス

MIT。OpenF1 は非公式プロジェクトであり、Formula 1 関連企業とは一切関係ありません。