一级方程式-MCP
项目介绍
技术文档摘要
Formula1 MCP 服务器！ 🏎️💨
基于TypeScript的Formula 1 MCP服务器，通过模型上下文协议将真实的实时和历史F1赛车数据直接带到您的指尖。
API状态： ✅ 21/22 OpenF1端点 + 10 Ergast端点工作
最后测试日期： 2025年11月10日
活跃工具： 29个MCP工具（所有历史数据免费，实时流媒体需要付费的OpenF1账户）
访问权限： 🎉 历史数据无需认证！
功能
- ✅ 免费的历史数据访问 - 无需认证！
- ✅ 全面的F1数据 - 赛事、车手、天气、遥测（2023年至今通过OpenF1）
- ✅ 历史数据 - 历史赛事信息（1950年至今通过Ergast API）
- ✅ 通过标准化的REST API访问F1赛事数据
- ✅ 实时遥测数据（车速、油门、刹车、RPM、DRS、档位）
- ✅ 车手和车队排名
- ✅ 天气数据（空气/赛道温度、湿度、风、降雨）
- ✅ 包含坐标的信息
- ✅ 团队无线电通信（音频URL）
- ✅ 赛事控制消息、旗帜和处罚
- ✅ 进站数据和轮胎策略
- ✅ 单圈时间和扇区分析
- ✅ 位置追踪和间隔
- ⚠️ 实时流媒体（MQTT） - 需要付费的OpenF1账户（当前已禁用）
📊 API 访问与定价
免费内容（无需账户）✅
所有历史数据完全免费！ 这包括：
- ✅ 所有从2023年至今的赛事（OpenF1）
- ✅ 所有从1950年至今的赛事（Ergast）
- ✅ 遥测、单圈时间、位置、进站
- ✅ 团队无线电录音、赛事控制消息
- ✅ 天气数据、车手信息、超车
- ✅ 测试功能：赛事结果、发车格
需要付费账户的内容 ⚠️
仅在实时比赛中进行实时流媒体：
- ❌ MQTT WebSocket流媒体（实时更新）
- ❌ 活动F1赛事期间的实时数据
- 📝 如需申请付费访问，请参阅此处
注意： 在比赛周末期间，即使没有付费账户，REST API端点仍可能用于获取延迟或最近的数据（待测试）。
对于详细的端点测试结果，请参阅**OPENF1_API_ACCESS_REPORT.md**。
开始使用
安装
- 克隆仓库：
git clone https://github.com/Panth1823/formula1-mcp
cd formula1-mcp
- 安装：
npm install
- 构建：
npm run build
就这样！对于历史数据，无需API密钥或认证。
使用方法
添加到您的Claude Desktop配置中：
{
"mcpServers": {
"formula1": {
"command": "node",
"args": ["<克隆仓库路径>/build/index.js"],
"cwd": "<克隆仓库路径>",
"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（字符串，必需）：从getHistoricalSessions获取的会话标识符driverNumber（字符串，可选）：车手的车辆编号以进行筛选
返回值： 无线电消息URL和时间戳
13. getRaceControlMessages
获取赛事控制消息（旗帜、事故、安全车时段）。
参数：
sessionKey（字符串，必需）：从getHistoricalSessions获取的会话标识符
返回值： 消息、类别、旗帜（黄色、红色、安全车）、受影响的车手编号
14. getRaceCalendar
获取F1赛事日历。
参数：
year（数字）：赛季年份（例如：2023）
15. getCircuitInfo
获取详细的赛道信息。
参数：
circuitId（字符串）：赛道标识符（例如："monza"，"spa"）
16. getSeasonList
获取可用的F1赛季列表。
参数：
limit（数字，可选）：要返回的赛季数量
17. getQualifyingResults
获取排位赛的结果。
参数：
year（数字）：赛季年份（例如：2023）round（数字）：比赛编号（例如：1，2，3）
18. getDriverInformation
从Ergast API获取详细的车手信息。
参数：
driverId（字符串）：车手标识符（例如："max_verstappen"，"lewis_hamilton"）
19. getConstructorInformation
从Ergast API获取详细的车队信息。
参数：
constructorId（字符串）：车队标识符（例如："red_bull"，"mercedes"）
20. clearCache
清除本地缓存中的F1数据。
参数：
- 无
数据来源
- 实时流媒体： OpenF1 MQTT - 实时MQTT/WebSocket流媒体，带有OAuth2
- 实时/近期数据： OpenF1 API - 实时遥测、位置、天气（REST）
- 历史数据： Ergast API - 完整的F1历史（1950-2024）
重要： Ergast API计划在2024赛季后停止更新。请为2025年及以后的替代历史数据源做好准备。
文档
- QUICK_START_STREAMING.md - 五分钟内开始实时流媒体
- LIVE_DATA_IMPLEMENTATION.md - 完整的技术文档
- COMPREHENSIVE_TEST_RESULTS.md - API测试结果和验证
- API_USAGE_ANALYSIS.md - 特性使用分析
已知问题
- getCurrentSessionStatus - 可能无法可靠工作（官方OpenF1 API中不存在此端点）
- 2024摩纳哥 - 返回0个会话（某些赛道的数据可能不可用）
- 冲刺赛 - 尚未支持（Ergast端点返回速率限制）
示例
实时流媒体（新！）：
- "当前比赛中的位置是什么？" → 使用
getLivePositions - "显示维斯塔潘的实时遥测数据" → 使用
getLiveCarData - "最新的赛事控制消息" → 使用
getLiveRaceControl - "当前天气状况" → 使用
getLiveWeather - "流媒体是否处于活动状态？" → 使用
getStreamingStatus
查找一个会话：
- "找到2024巴林大奖赛的比赛会话" → 使用
getHistoricalSessions - "获取2023摩纳哥排位赛的会话键" → 使用
getHistoricalSessions
历史查询：
- "显示2023摩纳哥GP的结果" → 使用
getHistoricRaceResults - "获取2024当前排名" → 使用
getDriverStandings+getConstructorStandings - "汉密尔顿在2023银石的单圈时间" → 使用
getLapTimes
实时数据（需要session_key）：
- "银石的天气" → 使用
getHistoricalSessions然后getWeatherData - "维斯塔潘的遥测数据" → 使用
getCarData加上车手编号和会话键 - "团队无线电消息" → 使用
getTeamRadio加上会话键
一般信息：
- "显示2024日历" → 使用
getRaceCalendar - "告诉我关于刘易斯·汉密尔顿" → 使用
getDriverInformation - "蒙扎赛道的信息" → 使用
getCircuitInfo
调试
使用MCP Inspector进行调试。
测试
该项目包含全面的API测试和实际验证：
# 测试OpenF1 API（12个测试）
npm run test:openf1
# 测试Ergast API（14个测试）
npm run test:ergast
# 测试两个API（26个测试）
npm run test:apis
最新测试结果： ✅ 26/26测试通过（100%）
详细结果见COMPREHENSIVE_TEST_RESULTS.md。
帮助
- 发现错误？在此处报告
- 有疑问？打开一个issue
- 想要帮助？提交PR
许可证
本项目根据MIT许可证发布 - 详情见LICENSE文件。