The Formula1 MCP Server ! 🏎️💨

Formula1 MCP 服务！🏎️💨

这是一款基于 TypeScript 的 Formula 1 MCP 服务，通过模型上下文协议，让您轻松获取 实时和历史 F1 赛车数据，感受赛车的激情。

API 状态： ✅ 21/22 个 OpenF1 端点 + 10 个 Ergast 端点可用
上次测试： 2025 年 11 月 10 日
活跃工具： 29 个 MCP 工具（所有历史数据均免费，实时流媒体需要付费 OpenF1 账户）
访问权限： 🎉 历史数据无需身份验证！

功能

• ✅ 免费访问历史数据——无需身份验证！
• ✅ 全面的 F1 数据——比赛场次、车手、天气、遥测（通过 OpenF1 提供 2023 年至今的数据）
• ✅ 历史数据——历史比赛信息（通过 Ergast API 提供 1950 年至今的数据）
• ✅ 通过标准化 REST API 访问 F1 比赛场次数据
• ✅ 实时遥测数据（赛车速度、油门、刹车、RPM、DRS、档位）
• ✅ 车手和车队积分榜
• ✅ 天气数据（空气/赛道温度、湿度、风、降雨量）
• ✅ 包含坐标的赛道信息
• ✅ 包含音频 URL 的车队无线电通信
• ✅ 比赛控制消息、旗帜和处罚
• ✅ 进站数据和轮胎策略
• ✅ 圈速和分段分析
• ✅ 位置追踪和间隔
• ⚠️ 实时流媒体（MQTT）——需要付费 OpenF1 账户（目前已禁用）

📊 API 访问权限与定价

免费内容（无需账户）✅

**所有历史数据完全免费！**包括：

• ✅ 2023 年至今的所有比赛场次（OpenF1）
• ✅ 1950 年至今的所有比赛（Ergast）
• ✅ 遥测、圈速、位置、进站
• ✅ 车队无线电录音、比赛控制消息
• ✅ 天气数据、车手信息、超车数据
• ✅ Beta 功能：比赛场次结果、发车位

哪些内容需要付费账户？⚠️

仅限比赛实时直播期间的实时流：

• ❌ 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（增强版）

获取当前/最新场次的实时单圈计时数据。现在连接处于活动状态时会使用流式传输！

参数：

• 无需参数

注意： 如果 MQTT 流处于活动状态，则返回其实时数据；否则使用 REST API。如果没有正在进行的实时场次，可能会返回空结果。

2. getCurrentSessionStatus

获取当前场次的状态信息。

参数：

• 无需参数

⚠️ 警告： 此端点可能无法可靠运行。OpenF1 API 没有标准的 /session_status 端点。

3. getDriverInfo

从 OpenF1 获取实时车手信息（需要场次上下文）。

参数：

• driverId（字符串）：车手编号（例如："1"、"44"、"33"）

注意： 如需获取历史车手数据，请改用 getDriverInformation。

4. getHistoricalSessions ⭐ 关键

查找历史赛事的场次键。必须先使用此工具获取其他工具所需的 session_key 值。

参数：

• year（数字，可选）：赛季年份（例如：2023、2024）
• circuit_short_name（字符串，可选）：赛道名称（例如："Monaco"、"Silverstone"、"Monza"）
• country_name（字符串，可选）：国家名称（例如："Italy"、"Belgium"）
• session_name（字符串，可选）：场次类型（例如："Race"、"Qualifying"、"Practice 1"）

示例： 查找 2024 年摩纳哥站正赛：year=2024, circuit_short_name="Monaco", session_name="Race"

5. getHistoricRaceResults

获取特定历史赛事的比赛结果。

参数：

• year（数字）：赛季年份（例如：2023）
• round（数字）：比赛轮次（例如：1、2、3）

6. getDriverStandings

获取车手锦标赛排名。

参数：

• year（数字）：赛季年份（例如：2023）

7. getConstructorStandings

获取车队锦标赛排名。

参数：

• year（数字）：赛季年份（例如：2023）

8. getLapTimes

获取特定车手的单圈时间。

参数：

• year（数字）：赛季年份（例如：2023）
• round（数字）：比赛轮次（例如：1、2、3）
• driverId（字符串）：车手标识符（例如："max_verstappen"、"lewis_hamilton"）

9. getWeatherData

获取某场次的天气数据。

参数：

• sessionKey（字符串，必填）：从 getHistoricalSessions 获取的场次标识符

返回： 空气/赛道温度、湿度、气压、风速/风向、降雨量

10. getCarData

获取详细的赛车遥测数据。

参数：

• driverNumber（字符串，必填）：车手的赛车编号（例如："1"、"44"、"33"）
• sessionKey（字符串，必填）：从 getHistoricalSessions 获取的场次标识符
• filters（字符串，可选）：其他筛选条件（例如："speed>=300"）

返回： 速度、油门百分比、刹车状态、RPM、挡位、DRS 状态（每场次 18K+ 个数据点）

11. getPitStopData

获取进站信息。

参数：

• driverNumber（字符串，可选）：车手的赛车编号
• sessionKey（字符串，可选）：场次标识符

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
• “显示 Verstappen 的实时遥测数据” → 使用 getLiveCarData
• “最新的赛事控制消息” → 使用 getLiveRaceControl
• “当前天气状况” → 使用 getLiveWeather
• “流式传输是否正在运行？” → 使用 getStreamingStatus

查找场次：

• “查找 2024 年巴林大奖赛正赛场次” → 使用 getHistoricalSessions
• “获取 2023 年摩纳哥排位赛的场次密钥” → 使用 getHistoricalSessions

历史查询：

• “显示 2023 年摩纳哥大奖赛结果” → 使用 getHistoricRaceResults
• “获取 2024 年当前积分榜” → 使用 getDriverStandings + getConstructorStandings
• “Hamilton 在 2023 年 Silverstone 的单圈用时” → 使用 getLapTimes

实时数据（需要 session_key）：

• “Silverstone 的天气” → 使用 getHistoricalSessions，然后使用 getWeatherData
• “Verstappen 的遥测数据” → 将车手号码和场次密钥与 getCarData 搭配使用
• “车队无线电消息” → 将场次密钥与 getTeamRadio 搭配使用

常规信息：

• “显示 2024 年赛历” → 使用 getRaceCalendar
• “介绍一下 Lewis Hamilton” → 使用 getDriverInformation
• “Monza 赛道信息” → 使用 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。

帮助

• 遇到 Bug？在此报告
• 有问题？请提交 Issue
• 想要协助？请提交 PR

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。