Fastf1 Mcp Server

fastf1-mcp

一个 MCP 服务，通过 FastF1 库向 AI 助手提供一级方程式数据。向 Claude（或任何兼容 MCP 的客户端）询问关于比赛结果、单圈时间、遥测数据、积分榜等方面的问题。

---

功能

• 36 个工具，涵盖积分榜、比赛结果、单圈时间、遥测数据、进站、排位赛、赛事控制、天气、比赛进程、轮胎磨损、弯道分析、DRS 区域和实时车手锦标赛预测
• 离线查看真实赛道地图 — 借助内置轮廓数据绘制 2018 年以来的所有 F1 赛道，无需下载
• 图表 — 赛道地图、速度曲线、比赛位置图、轮胎策略和单圈时间图，以 PNG 图像形式返回，可由 Claude 在消息中内嵌显示
• 实时回放桥接 — 跟随正在 f1-race-replay 中播放的比赛，并获取比赛工程师式解说
• 4 个 MCP 资源，用于赛程、车手、车队和赛道参考数据
• 6 个引导式提示词，用于比赛回顾、排位赛分析、策略深入分析、周末预览和实时回放解说
• 异步安全的 LRU 会话缓存 — 首次加载后，重复查询可即时返回
• 基于距离的遥测采样 — 将大型原始数据集压缩至 ≤ 500 个点
• 所有错误均以结构化字典形式返回 — 服务不会因错误输入而崩溃

---

展示

以下是服务图表工具生成的未经编辑的 PNG，与 Claude 在消息中内嵌显示的图像相同，数据来自通过 FastF1 获取的真实 F1 计时信息。每张图下方都列出了可生成该图的问题及其调用的工具。

“显示 Gasly 在 2020 年蒙扎站的最快圈速，并按速度着色。”  plot_track_map	“巴林 2022 年第 20 圈开始时，所有赛车在赛道上的位置分别在哪里？”  plot_track_map(at_lap=20)
“Hülkenberg 如何从 P19 跑上银石领奖台？”  plot_position_chart	“比较 Hamilton 和 Verstappen 在 2021 年吉达站的最快圈速。”  plot_speed_trace
“车队今年在中国站采用了哪些轮胎策略？”  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 年英国大奖赛的轮胎策略" 或 "谁领跑了 2021 年沙特阿拉伯大奖赛的每一圈，红旗何时出现？"

---

要求

• 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 .

两种方式都会在 http://localhost:6274 打开 Inspector。

---

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 遥测流主机（保持为 loopback 地址 — 该流未经身份验证）
FASTF1_MCP_REPLAY_STREAM_PORT	9999	f1-race-replay 遥测流端口
FASTF1_MCP_LOG_LEVEL	INFO	Python 日志级别

导出完整数据集以供分析

当用户需要文件而不是内嵌 JSON 时，get_lap_times、get_stint_analysis、get_lap_telemetry 和 compare_telemetry 会将批量数据数组通过 CSV 传递。

有两种方式可以触发导出：

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>/<auto-named>.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 实时计时 — 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 实时计时 — 2018 年至今）

工具	描述
get_lap_telemetry	获取指定单圈的遥测数据。
compare_telemetry	比较同一赛段中两位车手的遥测数据。
get_speed_trap_data	获取一个赛段中所有车手的测速点和最高速度数据。
get_sector_times	获取每位车手的最佳分段时间和理论最快单圈。
get_corner_analysis	分析一圈中每个弯道的弯心／入弯／出弯速度、挡位和刹车点；指定第二位车手时，还会显示双方各自获得或损失时间的位置。
get_drs_zones	根据 DRS 挡板实际开启的位置推断 DRS 区段（开启／关闭距离、长度及周边弯道），数据取自最快单圈，或正赛中 DRS 使用次数最多的单圈。适用于 2018–2025 年（2026 年起，DRS 已由主动空气动力学系统取代）。

正赛分析（FastF1 实时计时 — 2018 年至今）

工具	描述
get_race_control_messages	获取比赛控制信息流及赛段摘要：SC／VSC／红旗阶段（含圈数）、处罚、调查和赛道边界违规导致的成绩删除。可按类别、车手或圈数范围筛选。
get_weather	获取赛段期间的气温／赛道温度、湿度、风速和降雨情况，并将降雨时段对应到圈数。
get_position_changes	获取逐圈名次和与领跑者的差距、从发车位到终点的名次变化、领跑圈数及领跑者更替情况。
get_tyre_degradation	获取每个使用阶段和每种配方的燃油修正后轮胎衰退率，以及配方性能交叉点估算。适用于正赛和练习赛长距离测试。
get_championship_projection	获取假设比赛在任意一圈结束时车手和车队的积分榜，包括实时积分、比赛期间的领先者变化以及最终官方排名。支持冲刺赛周末，以及 2019–2024 年最快单圈积分规则。

图表（PNG 图片）

工具	描述
plot_speed_trace	绘制单圈速度与距离的关系，或叠加比较两位车手的数据，并显示时间差面板和弯道标记。
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 秒，并报告超车、进站和驶离维修区、安全车/虚拟安全车/红旗状态变化，以及新发布的比赛控制消息。

客户端会持续读取数据流并及时断开连接——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	各阶段轮胎使用情况 + 进站时机 + 轮胎退化 + 安全车/虚拟安全车时机 + 比赛速度——解释谁赢得了策略较量
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