MCP Sport

MCP Sport — F1 Telemetry MCP 🏎️

一个 MCP（Model Context Protocol） 服务，将 OpenF1 API 中的 Formula 1 数据作为工具提供给 AI 助手 （Claude Desktop、Cursor、MCP Inspector 等）。

全面覆盖：18 个数据工具，对应 OpenF1 文档中的 18 个端点—— 赛段、大奖赛周末、车手、成绩、单圈、进站、赛程阶段、遥测数据、 天气、锦标赛等。基于这些数据，还提供两个 MCP App 视图：车手积分榜和动态赛事回放。支持 渲染 MCP Apps 的宿主会显示 HTML。Cursor 和 Claude Desktop 不支持：它们 会以 JSON 形式返回相同的数据。

技术栈

层	技术
语言	Python 3.13+
MCP 框架	FastMCP 4.x
验证	Pydantic v2
数据	OpenF1 API（REST，2023 年及之后的历史数据免费）
项目管理	uv + pyproject.toml
传输	stdio

安装

# Clone and install dependencies
git clone https://github.com/andrequeiroz2/mcp-sport.git mcp-sport
cd mcp-sport
uv sync

使用方法

运行服务（stdio）

.venv/bin/python src/mcp_sport/server.py

MCP Inspector（用于测试工具的 Web UI）

npx @modelcontextprotocol/inspector@latest .venv/bin/python src/mcp_sport/server.py

在 Inspector UI 中：传输方式选择 STDIO，命令填写 .venv/bin/python， 参数填写 src/mcp_sport/server.py → 点击 Connect。

Claude Desktop / Cursor

将以下内容添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "f1-telemetry": {
      "command": "/absolute/path/mcp-sport/.venv/bin/python",
      "args": ["/absolute/path/mcp-sport/src/mcp_sport/server.py"]
    }
  }
}

18 个数据工具在两个客户端中均可使用。视图则无法在其中渲染。

视图（MCP Apps）

get_drivers_championship_view 和 get_race_replay_view 会返回交互式 HTML。Cursor 和 Claude Desktop 与 MCP Apps 不兼容：它们会 忽略 UI 并显示 JSON 数据。MCP Inspector 也会将结果视为文本。

这些视图已在官方 basic-host 中验证，该示例来自 modelcontextprotocol/ext-apps。 服务必须使用 HTTP，并通过 CORS 暴露 MCP 会话标头。 否则浏览器无法完成 Streamable HTTP 握手。

终端 1 — 运行在端口 8765 上的 MCP 服务：

uv run python -c "
import uvicorn
from starlette.middleware import Middleware
from starlette.middleware.cors import CORSMiddleware
from mcp_sport.server import mcp

app = mcp.http_app(middleware=[Middleware(
    CORSMiddleware,
    allow_origins=['*'],
    allow_methods=['*'],
    allow_headers=['*'],
    expose_headers=['mcp-session-id', 'mcp-protocol-version'],
)])
uvicorn.run(app, host='127.0.0.1', port=8765)
"

终端 2 — basic-host（需要 Node.js；npm start 需要 bun，因此请使用 tsx）：

git clone --depth 1 https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps/examples/basic-host
npm install
npm run build
SERVERS='["http://127.0.0.1:8765/mcp"]' npx tsx serve.ts

打开 http://localhost:8080（沙盒位于 :8081），然后调用 get_drivers_championship_view 或 get_race_replay_view。更改视图 HTML 后， 请先强制刷新页面（Ctrl+Shift+R），再重新运行工具。 宿主会缓存 ui:// 资源。

可用工具（18 个）

领域	工具	描述
导航	get_sessions	赛段（练习赛、排位赛、冲刺赛、正赛）
	get_meetings	大奖赛和测试周末
名录	get_drivers	按赛段/大奖赛周末查询车手
成绩	get_session_results	赛段最终排名
	get_starting_grid	发车位次
	get_positions	整个赛段中的位置历史
赛事	get_laps	单圈时间、分段和速度
	get_pit_stops	进站
	get_stints	赛程阶段和轮胎配方
	get_intervals	实时差距（与领跑者和前车的差距）
	get_race_control	旗帜、安全车、事故
赛事背景	get_weather	赛道天气（每分钟采样）
	get_overtakes	超车
	get_team_radio	车队无线电片段（MP3）
遥测数据	get_car_data	速度、转速、挡位、油门、刹车、DRS（约 3.7 Hz）
	get_location	车辆在赛道上的近似位置（约 3.7 Hz）
锦标赛	get_drivers_championship	车手积分榜（测试版）
	get_teams_championship	车队积分榜（测试版）

与 AI 的对话示例

“诺里斯在最近两场比赛中获得了多少积分？”

AI 会依次调用：get_sessions(session_type="Race") 以查找最近的 赛段 → 对每个赛段调用 get_session_results(session_key=..., driver_number=4)。

项目结构

src/mcp_sport/
├── server.py           # Entrypoint: FastMCP instance + tool registration
├── exceptions.py       # Domain exceptions
├── logging_config.py   # Logging to stderr (stdout is the protocol channel)
├── clients/openf1.py   # Single OpenF1 HTTP client
├── schemas/            # Pydantic: input (BaseInput) and output per endpoint
├── validators/         # Business validations per endpoint
├── services/           # Orchestration per endpoint
├── tools/              # MCP tools (thin layer) per endpoint
└── apps/               # MCP App views (Custom HTML, ui:// resource)
    ├── championship_view.py  # Drivers standings board
    └── race_replay_view.py   # Animated race replay

规范文档

文档	内容
docs/Technical_Reference.md	技术栈、版本和官方链接（权威信息源）
docs/Architectural_Design.md	新端点的实现模式和操作流程
docs/Logging_Strategy.md	日志策略（stderr + 每次请求的遥测数据）
tasks/	已计划和已执行任务的历史记录

配置

变量	默认值	说明
MCP_SPORT_LOG_LEVEL	INFO	stderr 日志级别（DEBUG、INFO、WARNING、ERROR）

已知限制

• 历史数据从 2023 年起提供；实时数据需要付费的 OpenF1 订阅
• 在官方结果发布之前，session_result 和 starting_grid 会返回 HTTP 404
• 遥测数据（car_data、location）每场比赛/每位车手会返回 18–24k 个样本。 使用范围筛选条件（例如 speed_min 和 date_from/date_to）缩小查询范围
• OpenF1 的锦标赛端点目前处于 beta 阶段

许可证

MIT。OpenF1 是一个非官方项目，与任何一级方程式公司均无任何 关联。