Fastf1 Mcp Server

fastf1-mcp

FastF1 ライブラリを通じて、Formula 1 のデータを AI アシスタントに提供する MCP サーバーです。Claude（または MCP 対応クライアント）に、レース結果、ラップタイム、テレメトリー、ランキングなどについて質問できます。

---

機能

• 36 個のツールでランキング、レース結果、ラップタイム、テレメトリー、ピットストップ、予選、レースコントロール、天候、レースの展開、タイヤの劣化、コーナー分析、DRS ゾーン、ライブのチャンピオンシップ予測に対応
• 実際のサーキットマップをオフラインで表示 — 2018 年以降のすべての F1 サーキットを、同梱の輪郭データから描画します。ダウンロードは不要です
• チャート — トラックマップ、速度推移、レース順位チャート、タイヤ戦略、ラップタイムのプロットを PNG 画像として返します。Claude は画像をインライン表示できます
• ライブリプレイブリッジ — f1-race-replay で再生中のレースを追い、レースエンジニアの解説を受け取れます
• スケジュール、ドライバー、コンストラクター、サーキットの参照データを提供する 4 つの MCP リソース
• レースの振り返り、予選分析、戦略の詳細分析、週末のプレビュー、ライブリプレイの解説に使える 6 つのガイド付きプロンプト
• 非同期処理に安全な LRU セッションキャッシュ — 初回の読み込み後は、同じクエリに即座に応答します
• 距離ベースのテレメトリーサンプリング — 大きな未加工データセットを ≤ 500 ポイントに圧縮します
• すべてのエラーを構造化辞書として返すため、不正な入力があってもサーバーがクラッシュすることはありません

---

ギャラリー

以下は、サーバーのチャートツールが出力する未編集の PNG 画像です。FastF1 経由で取得した実際の F1 計時データから描画したもので、Claude がインライン表示する画像と同じものです。それぞれの画像の下には、画像を表示する質問と呼び出すツールを記載しています。

「2020年モンツァでのGaslyの最速ラップを速度で色分けして表示して。」  plot_track_map	「2022年バーレーンの20周目が始まったとき、全員はコース上のどこにいた？」  plot_track_map(at_lap=20)
「HülkenbergはシルバーストンでどうやってP19から表彰台まで上がった？」  plot_position_chart	「2021年ジェッダでのHamiltonとVerstappenの最速ラップを比較して。」  plot_speed_trace
「今年の中国GPで、各チームはどんなタイヤ戦略を採った？」  plot_tyre_strategy	「2026年のカレンダーにあるすべてのサーキットを描いて。」 オフラインで動作します。  plot_circuit(year=2026)

---

クイックスタート

クローンは不要です。uv で公開済みのパッケージを実行できます。

Claude Code

claude mcp add fastf1 -- uvx fastf1-mcp-server

Claude Desktop — claude_desktop_config.json に追加して、再起動します。

{
  "mcpServers": {
    "fastf1": {
      "command": "uvx",
      "args": ["fastf1-mcp-server"]
    }
  }
}

次のように尋ねてみましょう：「2025年イギリスGPのタイヤ戦略をプロットして」、または 「2021年サウジアラビアGPで全周回をリードしたのは誰ですか？ 赤旗はいつ出ましたか？」

---

要件

• Python 3.12+
• uv（推奨）または pip

---

インストール

uv を使用する場合（推奨）

git clone https://github.com/Surya96t/fastf1-mcp
cd fastf1-mcp
uv sync

pip を使用する場合

pip install fastf1-mcp-server

---

サーバーの実行

# via uv (development)
uv run fastf1-mcp-server

# or directly
python -m fastf1_mcp

MCP Inspector（開発／デバッグ）

# Option A — official npx inspector
npx @modelcontextprotocol/inspector uv --directory . run fastf1-mcp-server

# Option B — fastmcp wrapper
uv run fastmcp dev inspector -m fastf1_mcp.server --with-editable .

どちらの場合も、Inspector は http://localhost:6274 で開きます。

---

Claude Desktop の設定（クローンから実行する場合）

以下を ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "fastf1": {
      "command": "uv",
      "args": ["run", "fastf1-mcp-server"],
      "cwd": "/absolute/path/to/fastf1-mcp",
      "env": {
        "FASTF1_MCP_LOG_LEVEL": "INFO",
        "FASTF1_MCP_MAX_CACHED_SESSIONS": "10"
      }
    }
  }
}

保存後に Claude Desktop を再起動します。ツールパネルにサーバー名 fastf1 が表示されます。

---

設定

すべての設定は、FASTF1_MCP_ プレフィックスが付いた環境変数から読み込まれます。

変数	デフォルト	説明
FASTF1_MCP_FASTF1_CACHE_PATH	~/.fastf1_cache	FastF1 セッションファイル用のディスクキャッシュ
FASTF1_MCP_MAX_CACHED_SESSIONS	10	メモリに保持するセッションの最大数（LRU）
FASTF1_MCP_DEFAULT_TELEMETRY_SAMPLES	200	テレメトリのデフォルトサンプル点数
FASTF1_MCP_MAX_TELEMETRY_SAMPLES	500	テレメトリのサンプル点数の上限
FASTF1_MCP_EXPORT_DIR	./fastf1-exports	CSV エクスポート用ディレクトリ（サーバーの作業ディレクトリを基準とする相対パス）
FASTF1_MCP_AUTO_EXPORT_ROWS	50	一括配列の行数がこの値を超えた場合に CSV へ自動エクスポートします。無効にするには 0 を設定します。
FASTF1_MCP_REPLAY_STREAM_HOST	127.0.0.1	f1-race-replay のテレメトリストリームのホスト（ストリームは認証されていないため、ループバックのままにしてください）
FASTF1_MCP_REPLAY_STREAM_PORT	9999	f1-race-replay のテレメトリストリームのポート
FASTF1_MCP_LOG_LEVEL	INFO	Python のログレベル

分析用に全データセットをエクスポートする

get_lap_times、get_stint_analysis、get_lap_telemetry、および compare_telemetry は、ユーザーがインライン JSON ではなくファイルを必要とする場合、 一括データ配列を CSV 経由で出力します。

エクスポートが実行される方法は 2 通りあります。

1. 自動エクスポート（大きな応答でのデフォルト）— 応答の 一括配列が FASTF1_MCP_AUTO_EXPORT_ROWS の行数（デフォルトは 50）を超える場合、 サーバーはそれを FASTF1_MCP_EXPORT_DIR 内の CSV に書き込み、配列の代わりに exportPath と note を応答に含めます。これにより、全レースのラップタイム検索、 全グリッドのスティント分析、200 点のテレメトリトレースなど、MCP クライアントが 応答を中身の分からない一時ファイルに黙って書き出してしまうケースをカバーします。
2. 明示的な export_path パラメーター — ツール呼び出し時に渡します。
   • export_path=True → <FASTF1_MCP_EXPORT_DIR>/<自動生成された名前>.csv に書き込みます
   • export_path="data/laps" → 指定したディレクトリに自動生成された名前のファイルを書き込みます
   • export_path="data/ver-monaco.csv" → 指定したファイルに書き込みます

summary フィールドは常に含まれるため、チャットだけを使うユーザーも ファイルを開かずに「最速ラップはどれか／戦略はどうだったか」に答えられます。 相対パスは MCP サーバーの作業ディレクトリを基準に解決されます。 Claude Desktop では MCP 設定で指定した cwd が作業ディレクトリになるため、 デフォルトではユーザーのプロジェクトディレクトリにファイルが保存されます。

---

ツール

クイック検索（Ergast API — 1950年から現在まで）

ツール	説明
get_schedule	シーズンの F1 レースカレンダーを取得します。
get_driver_standings	ドライバー選手権の順位を取得します。
get_constructor_standings	コンストラクター選手権の順位を取得します。
get_driver_info	ドライバー情報を取得します。
get_race_results_historical	過去のレース結果を取得します（2018年より前、またはセッションデータが利用できない場合）。
get_circuit_info	サーキット情報を取得します。

セッションデータ（FastF1 Live Timing — 2018年以降）

ツール	説明
get_session_results	セッションの順位／結果を取得します。
get_lap_times	セッション中のドライバーの全ラップタイムを取得します。
get_fastest_laps	セッション中の各ドライバーの最速ラップを取得します。
get_race_pace	全ドライバーの平均レースペースを計算します。
get_stint_analysis	レースのタイヤスティントを分析します。
get_pit_stops	レース中の全ピットストップを取得します。
get_qualifying_breakdown	Q1／Q2／Q3別の予選結果を取得します。

テレメトリー（FastF1 Live Timing — 2018年以降）

ツール	説明
get_lap_telemetry	特定のラップのテレメトリーデータを取得します。
compare_telemetry	同じセッションにおける2人のドライバーのテレメトリーを比較します。
get_speed_trap_data	セッション中の全ドライバーのスピードトラップと最高速度のデータを取得します。
get_sector_times	各ドライバーの最速セクタータイムと理論上の最速ラップを取得します。
get_corner_analysis	1周分のコーナーごとの頂点／進入／立ち上がり速度、ギア、ブレーキポイントを取得します。2人目のドライバーを指定すると、各コーナーでどちらがタイムを稼いだか、または失ったかも取得します。
get_drs_zones	フラップが実際に開いた場所（最速ラップ、またはレースではDRSの使用が最も多かったラップ）から推定したDRSゾーン（開閉地点までの距離、長さ、周辺のコーナー）を取得します。2018～2025年が対象です（2026年にDRSはアクティブエアロに置き換えられました）。

レース分析（FastF1 Live Timing — 2018年以降）

ツール	説明
get_race_control_messages	セッションの概要を含むレースコントロールのフィードを取得します。SC／VSC／赤旗の期間（該当ラップを含む）、ペナルティ、調査、トラックリミット違反によるタイム抹消が含まれます。カテゴリー、ドライバー、ラップ範囲で絞り込めます。
get_weather	セッション中の気温／路面温度、湿度、風、降雨を取得し、降雨の時間帯をラップに対応付けます。
get_position_changes	ラップごとの順位と首位との差、グリッドからフィニッシュまでの順位変動、首位走行ラップ数、首位の入れ替わりを取得します。
get_tyre_degradation	スティント別およびコンパウンド別の燃料補正済みデグラデーション率と、コンパウンドの優劣が入れ替わる推定時点を取得します。レースとプラクティスのロングランに対応しています。
get_championship_projection	レースが任意のラップで終了した場合のドライバーズおよびコンストラクターズの順位を取得します。リアルタイムのポイント、レース中の順位変動、最終的な公式順位を含みます。スプリント週末と、2019～2024年のファステストラップポイントにも対応しています。

チャート（PNG画像）

ツール	説明
plot_speed_trace	1周分、または2人のドライバーを重ね合わせた速度と距離のグラフを作成します。重ね合わせ表示ではタイム差パネルとコーナーマーカーも表示します。
plot_position_chart	レースの履歴チャートを作成します。全ドライバーのラップごとの順位を表示し、最大8人を強調表示できます。
plot_tyre_strategy	フィニッシュ順に並べたスティントバーを、コンパウンドごとに色分けし、文字も付けて表示します。
plot_lap_times	最大3人のドライバーについて、ラップごとのラップタイムを表示します。マーカーの形はコンパウンドを示します。
plot_track_map	速度またはギアで色分けしたラップのサーキットマップを作成します。番号付きコーナー、DRSゾーン、進行方向も表示します。at_lapを指定すると、そのラップ開始時点の全車のコース上の位置を表示します。FastF1のテレメトリーをダウンロードできない場合は、保存されているコースアウトラインを使用します。
plot_circuit	同梱データから実際のサーキットのアウトラインを表示します。オフラインで動作します。サーキット名（「Monaco」、「COTA」、「Spa」）、グランプリ名、または年＋ラウンドで指定できます。年のみを指定すると、そのシーズンのサーキット一覧を表示します。公式コース長、レースの進行方向、スタート／フィニッシュを表示します。

すべてのチャートツールでsave_pathを指定すると、PNGをエクスポートディレクトリにも保存できます。plot_speed_traceはDRSが作動していた区間も網掛けで表示します。

ライブリプレイ（f1-race-replay）

リプレイ再生中に、f1-race-replayがlocalhost:9999で配信するテレメトリストリームを読み取ります。そこでリプレイを開始し（python main.py --viewer --year 2024 --round 12）、Claudeに何が起きているか尋ねてください。

ツール	説明
get_replay_state	スナップショット：リプレイ時刻、ラップ、首位ドライバー、コース状況、セーフティカー、天候、ライブ順位表（タイヤ、速度、DRS、ピット、タイム差）、最新のレースコントロールメッセージ。
watch_replay	N秒間監視し、オーバーテイク、ピットイン／アウト、SC／VSC／赤旗の変化、新しいレースコントロールメッセージを報告します。

クライアントはストリームを継続的に読み取り、速やかに切断します。f1-race-replayのサーバーはレンダリングスレッド上で書き込みを行うため、読み取りを停止したクライアントがあるとリプレイがフリーズします。

ユーティリティ

ツール	説明
list_events	シーズン内のすべてのイベントを一覧表示します。
list_drivers	シーズン内のすべてのドライバーを一覧表示します。必要に応じて特定のイベントで絞り込めます。
get_cache_status	サーバーのメモリ内セッションキャッシュの状態を確認します。
clear_cache	メモリ内ストレージからキャッシュ済みセッションを削除します。

---

リソース

URI	説明
f1://schedule/{year}	シーズンの全レースカレンダー
f1://drivers/{year}	シーズンに参戦したすべてのドライバー
f1://constructors/{year}	シーズンに参戦したすべてのコンストラクター
f1://circuits	F1の全サーキット（全期間）

---

プロンプト

プロンプト	引数	内容
race_recap	year, event	結果＋順位変動＋レースコントロール＋最速ラップ＋スティントを提示し、レースを解説します
qualifying_analysis	year, event	Qの分析＋セクタータイム＋ポールラップのコーナー分析
driver_comparison	year, driver1, driver2	シーズン単位の直接対決：順位、レース、予選
strategy_analysis	year, event	スティント＋ピットのタイミング＋タイヤの劣化＋SC／VSCのタイミング＋レースペースを分析し、戦略勝負の勝者を解説します
weekend_preview	year, event	サーキットの詳細＋最近の歴史＋チャンピオンシップの状況
replay_commentary	rounds	f1-race-replayで再生中のリプレイについて、レースエンジニアの無線更新を提供します

---

使用例のクエリ（Claude Desktop）

Who won the 2024 Monaco Grand Prix and what was the strategy?
→ use race_recap prompt or call get_session_results + get_stint_analysis

Compare Verstappen and Leclerc's telemetry in 2024 Monaco qualifying
→ compare_telemetry(2024, "Monaco", "Q", "VER", "LEC")

Who had the fastest theoretical lap in 2024 Silverstone qualifying?
→ get_sector_times(2024, "Silverstone", "Q")

Where did Norris lose pole to Verstappen in 2024 Spain qualifying?
→ get_corner_analysis(2024, "Spain", "Q", "NOR", driver2="VER")

Why did everyone pit on lap 34? Were there any penalties?
→ get_race_control_messages(2024, "Hungary")

How quickly did the mediums degrade compared to the hards?
→ get_tyre_degradation(2024, "Bahrain")

Show me how the 2024 Brazil race unfolded
→ plot_position_chart(2024, "Brazil", highlight=["VER", "NOR", "RUS"])

Where was everyone when the safety car came out on lap 34?
→ plot_track_map(2024, "Hungary", "R", at_lap=34)

Draw the Suzuka circuit / show me all the 2026 tracks
→ plot_circuit("Suzuka") / plot_circuit(year=2026)

Who was leading the championship on the road at half distance in Abu Dhabi?
→ get_championship_projection(2024, "Abu Dhabi", after_lap=29)

What's happening in the replay right now?
→ get_replay_state() / watch_replay(duration_sec=10)

Show me the 2024 constructor standings after round 10
→ get_constructor_standings(2024, after_round=10)

---

開発

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=fastf1_mcp

# Lint
uv run ruff check src/

---

データソースと対象範囲

ソース	対象範囲	用途
Ergast API（FastF1経由）	1950年～現在	順位、スケジュール、過去の結果、サーキット情報
FastF1 Live Timing	2018年～現在	ラップタイム、テレメトリ、予選、ピットストップ、タイヤデータ、レースコントロール、天候
MultiViewer（FastF1経由）	2018年～現在	サーキットのコーナー位置（コーナー分析、速度トレースのマーカー）
bacinger/f1-circuits（同梱、MIT）	2018～2026年に使用された全F1サーキット＋クラシックサーキット	オフラインでのサーキットアウトラインと2020～2026年のカレンダー（plot_circuit、トラックマップのフォールバック）

注： FastF1のセッションデータは2018年以降のみ利用できます。それ以前のシーズンにはget_race_results_historicalを使用してください。

---

ライセンス

MIT