F1 MCP Server Node Implementation

Formula1 MCP サーバー ! 🏎️💨

TypeScript ベースの Formula 1 MCP サーバーです。Model Context Protocol を通じて、F1 のリアルタイムデータと過去のレースデータをすぐに利用できます。

API のステータス： ✅ OpenF1 の 22 エンドポイント中 21 エンドポイント + Ergast の 10 エンドポイントが動作
最終テスト日： 2025 年 11 月 10 日
有効なツール： MCP ツール 29 個（過去のデータはすべて無料、ライブストリーミングには有料の OpenF1 アカウントが必要です）
アクセス： 🎉 過去のデータは認証不要です！

機能

• ✅ 過去のデータに無料でアクセス - 認証不要です！
• ✅ 包括的な F1 データ - セッション、ドライバー、天候、テレメトリー（OpenF1 経由で 2023 年から現在まで）
• ✅ 過去のデータ - 過去のレース情報（Ergast API 経由で 1950 年から現在まで）
• ✅ 標準化された REST API 経由で F1 セッションデータにアクセス
• ✅ リアルタイムのテレメトリーデータ（車速、スロットル、ブレーキ、RPM、DRS、ギア）
• ✅ ドライバーおよびコンストラクターの順位
• ✅ 天候データ（気温／路面温度、湿度、風、降雨量）
• ✅ 座標付きのサーキット情報
• ✅ 音声 URL 付きのチームラジオ通信
• ✅ レースコントロールのメッセージ、旗、ペナルティ
• ✅ ピットストップデータとタイヤ戦略
• ✅ ラップタイムとセクター分析
• ✅ ポジション追跡とタイム差
• ⚠️ ライブストリーミング（MQTT）- 有料の OpenF1 アカウントが必要です（現在無効）

📊 API アクセスと料金

無料で利用できるもの（アカウント不要） ✅

過去のデータはすべて完全無料です！ 以下が含まれます：

• ✅ 2023 年から現在までの全セッション（OpenF1）
• ✅ 1950 年から現在までの全レース（Ergast）
• ✅ テレメトリー、ラップタイム、ポジション、ピットストップ
• ✅ チームラジオの録音、レースコントロールのメッセージ
• ✅ 天候データ、ドライバー情報、オーバーテイク
• ✅ ベータ機能：セッション結果、スターティンググリッド

有料アカウントが必要なもの ⚠️

ライブレース中のリアルタイムストリーミングのみ：

• ❌ MQTT WebSocket ストリーミング（ライブ更新）
• ❌ F1 セッション開催中のリアルタイムデータ
• 📝 必要な場合は有料アクセスを申請してください

注記： 有料アカウントがなくても、レース週末に REST API エンドポイントから遅延データや最近のデータを取得できる場合があります（要テスト）。

エンドポイントの詳細なテスト結果については、OPENF1_API_ACCESS_REPORT.md をご覧ください。

はじめに

インストール

1. リポジトリをクローンします：

git clone https://github.com/Panth1823/formula1-mcp
cd formula1-mcp

2. インストールします：

npm install

3. ビルドします：

npm run build

これで完了です！過去のデータには API キーも認証も必要ありません。

使い方

Claude Desktop の設定に追加します：

{
  "mcpServers": {
    "formula1": {
      "command": "node",
      "args": ["<path-to-your-cloned-repo>/build/index.js"],
      "cwd": "<path-to-your-cloned-repo>",
      "enabled": true
    }
  }
}

設定ファイルの場所：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

利用可能なツール

🏎️ ライブデータツール

これらのツールは、F1 セッション開催中（レース週末）にライブデータを返します。セッションが開催されていない場合は、空の配列または最後に取得可能だったデータを返します。

注記： リアルタイムの MQTT ストリーミングには有料の OpenF1 アカウントが必要です。レース週末の REST API アクセスは、支払いなしでも利用できる場合があります（要テスト）。

1. getLiveCarData

全ドライバーの車両テレメトリー（速度、スロットル、ブレーキ、RPM、DRS、ギア）を取得します。

パラメーター： なし
戻り値： 車両テレメトリーデータの配列（セッションが開催されていない場合は空）
無料アクセス： ⚠️ 次回のレース週末にテスト予定

2. getLivePositions

現在のコース上のポジションとタイム差を取得します。

パラメーター： なし
戻り値： タイム差付きのポジションデータの配列（セッションが開催されていない場合は空）
無料アクセス： ⚠️ 次回のレース週末にテスト予定

3. getLiveRaceControl

最近のレースコントロールのメッセージ（旗、ペナルティ、セーフティカー）を取得します。

パラメーター： なし
戻り値： レースコントロールのメッセージの配列
データソース： MQTT ストリーム（ライブ）または REST API（フォールバック）

4. getLiveTeamRadio

音声 URL 付きの最近のチームラジオ通信を取得します。

パラメーター： なし
戻り値： チームラジオメッセージの配列
データソース： MQTT ストリーム（ライブ）または REST API（フォールバック）

5. getLiveWeather

現在の気象状況を取得します。

パラメーター： なし
戻り値： 気象データオブジェクト
データソース： MQTT ストリーム（ライブ）または REST API（フォールバック）

6. getStreamingStatus

ストリーミングの接続状況とデータの有無を確認します。

パラメーター： なし
戻り値： 接続状況とデータカウンター

7. startStreaming

MQTT ストリーミング接続を手動で開始します。

パラメーター： なし
必要条件： MQTT_ENABLED=true および有効な認証情報

8. stopStreaming

ストリーミングを停止し、ライブデータのキャッシュを消去します。

パラメーター： なし

---

履歴データツール

1. getLiveTimingData (Enhanced)

現在／最新のセッションのリアルタイムラップタイミングデータを取得します。ストリーミングが有効な場合はストリーミングを使用するようになりました！

パラメーター：

• 必須項目なし

注： MQTT ストリームが有効な場合はそこからライブデータを返し、それ以外の場合は REST API を使用します。ライブセッションがアクティブでない場合、空のデータを返すことがあります。

2. getCurrentSessionStatus

現在のセッションに関するステータス情報を取得します。

パラメーター：

• 必須項目なし

⚠️ 警告： このエンドポイントは安定して動作しない場合があります。OpenF1 API には標準の /session_status エンドポイントがありません。

3. getDriverInfo

OpenF1 からリアルタイムのドライバー情報を取得します（セッションコンテキストが必要です）。

パラメーター：

• driverId（string）：ドライバー番号（例："1"、"44"、"33"）

注： 過去のドライバーデータには、代わりに getDriverInformation を使用してください。

4. getHistoricalSessions ⭐ 重要

過去のイベントのセッションキーを検索します。他のツールで必要な session_key の値を取得するには、必ず最初にこのツールを使用してください。

パラメーター：

• year（number、任意）：シーズンの年（例：2023、2024）
• circuit_short_name（string、任意）：サーキット名（例："Monaco"、"Silverstone"、"Monza"）
• country_name（string、任意）：国名（例："Italy"、"Belgium"）
• session_name（string、任意）：セッションの種類（例："Race"、"Qualifying"、"Practice 1"）

例： 2024 年のモナコグランプリのレースを検索：year=2024, circuit_short_name="Monaco", session_name="Race"

5. getHistoricRaceResults

過去の特定のレースの結果を取得します。

パラメーター：

• year（number）：シーズンの年（例：2023）
• round（number）：レース番号（例：1、2、3）

6. getDriverStandings

ドライバーズチャンピオンシップの順位を取得します。

パラメーター：

• year（number）：シーズンの年（例：2023）

7. getConstructorStandings

コンストラクターズチャンピオンシップの順位を取得します。

パラメーター：

• year（number）：シーズンの年（例：2023）

8. getLapTimes

特定のドライバーのラップタイムを取得します。

パラメーター：

• year（number）：シーズンの年（例：2023）
• round（number）：レース番号（例：1、2、3）
• driverId（string）：ドライバー識別子（例："max_verstappen"、"lewis_hamilton"）

9. getWeatherData

セッションの気象データを取得します。

パラメーター：

• sessionKey（string、必須）：getHistoricalSessions から取得したセッション識別子

戻り値： 気温／路面温度、湿度、気圧、風速／風向、降雨量

10. getCarData

詳細な車両テレメトリデータを取得します。

パラメーター：

• driverNumber（string、必須）：ドライバーの車両番号（例："1"、"44"、"33"）
• sessionKey（string、必須）：getHistoricalSessions から取得したセッション識別子
• filters（string、任意）：追加のフィルター（例："speed>=300"）

戻り値： 速度、スロットル開度（%）、ブレーキ状態、RPM、ギア、DRS 状態（1 セッションあたり 18K 件以上のデータポイント）

11. getPitStopData

ピットストップ情報を取得します。

パラメーター：

• driverNumber（string、任意）：ドライバーの車両番号
• sessionKey（string、任意）：セッション識別子

12. getTeamRadio

チームラジオの通信を取得します。

パラメーター：

• sessionKey（string、必須）：getHistoricalSessions から取得したセッション識別子
• driverNumber（string、任意）：絞り込み対象となるドライバーのカーナンバー

**戻り値：**無線メッセージの URL とタイムスタンプ

13. getRaceControlMessages

レースコントロールのメッセージ（旗、インシデント、セーフティカー導入期間）を取得します。

パラメーター：

• sessionKey（string、必須）：getHistoricalSessions から取得したセッション識別子

**戻り値：**メッセージ、カテゴリ、旗（黄旗、赤旗、セーフティカー）、影響を受けたドライバーのカーナンバー

14. getRaceCalendar

F1 のレースカレンダーを取得します。

パラメーター：

• year（number）：シーズンの年（例：2023）

15. getCircuitInfo

サーキットの詳細情報を取得します。

パラメーター：

• circuitId（string）：サーキット識別子（例："monza"、"spa"）

16. getSeasonList

利用可能な F1 シーズンの一覧を取得します。

パラメーター：

• limit（number、任意）：取得するシーズン数

17. getQualifyingResults

予選セッションの結果を取得します。

パラメーター：

• year（number）：シーズンの年（例：2023）
• round（number）：レース番号（例：1、2、3）

18. getDriverInformation

Ergast API からドライバーの詳細情報を取得します。

パラメーター：

• driverId（string）：ドライバー識別子（例："max_verstappen"、"lewis_hamilton"）

19. getConstructorInformation

Ergast API からコンストラクターの詳細情報を取得します。

パラメーター：

• constructorId（string）：コンストラクター識別子（例："red_bull"、"mercedes"）

20. clearCache

F1 データのローカルキャッシュを消去します。

パラメーター：

• 必須パラメーターなし

データソース

• ライブストリーミング：OpenF1 MQTT - OAuth2 を使用したリアルタイムの MQTT/WebSocket ストリーミング
• ライブ／最新データ：OpenF1 API - リアルタイムのテレメトリー、順位、天候（REST）
• 過去のデータ：Ergast API - F1 の完全な歴史（1950～2024 年）

**重要：**Ergast API は 2024 年シーズン以降、更新を停止する予定です。2025 年以降に利用する代替の過去データソースを検討してください。

ドキュメント

• QUICK_START_STREAMING.md - ライブストリーミングを 5 分で始める
• LIVE_DATA_IMPLEMENTATION.md - 技術ドキュメントの全容
• COMPREHENSIVE_TEST_RESULTS.md - API のテスト結果と検証
• API_USAGE_ANALYSIS.md - 機能の利用状況分析

既知の問題

1. getCurrentSessionStatus - 正しく動作しない場合があります（公式 OpenF1 API にエンドポイントがありません）
2. Monaco 2024 - 0 件のセッションが返されます（すべてのサーキットでデータを利用できるとは限りません）
3. スプリントレース - まだサポートされていません（Ergast のエンドポイントがレート制限を返します）

使用例

ライブストリーミング（新機能！）：

• 「レースの現在の順位は？」→ getLivePositions を使用
• 「フェルスタッペンのライブテレメトリーを表示して」→ getLiveCarData を使用
• 「最新のレースコントロールメッセージ」→ getLiveRaceControl を使用
• 「現在の天候状況は？」→ getLiveWeather を使用
• 「ストリーミングは有効？」→ getStreamingStatus を使用

セッションの検索：

• 「2024 年バーレーン GP のレースセッションを検索して」→ getHistoricalSessions を使用
• 「2023 年モナコ予選のセッションキーを取得して」→ getHistoricalSessions を使用

過去のデータに関する問い合わせ：

• 「2023 年モナコ GP の結果を表示して」→ getHistoricRaceResults を使用
• 「2024 年現在のランキングを取得して」→ getDriverStandings と getConstructorStandings を使用
• 「2023 年シルバーストンでのハミルトンのラップタイム」→ getLapTimes を使用

ライブデータ（session_key が必要）：

• 「シルバーストンの天候」→ getHistoricalSessions の後に getWeatherData を使用
• 「フェルスタッペンのテレメトリー」→ ドライバー番号とセッションキーを指定して getCarData を使用
• 「チームラジオのメッセージ」→ セッションキーを指定して getTeamRadio を使用

一般情報：

• 「2024 年のカレンダーを表示して」→ getRaceCalendar を使用
• 「ルイス・ハミルトンについて教えて」→ getDriverInformation を使用
• 「モンツァ・サーキットの情報」→ getCircuitInfo を使用

デバッグ

デバッグには MCP Inspector を使用してください。

テスト

このプロジェクトには、実環境での検証を含む包括的な API テストが用意されています。

# Test OpenF1 API (12 tests)
npm run test:openf1

# Test Ergast API (14 tests)  
npm run test:ergast

# Test both APIs (26 tests)
npm run test:apis

最新のテスト結果： ✅ 26/26 件のテストに合格（100％）
詳細な結果については、COMPREHENSIVE_TEST_RESULTS.md をご覧ください。

ヘルプ

• バグを見つけましたか？こちらから報告してください
• 質問がありますか？Issue を作成してください
• 協力したいですか？PR を送信してください

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。