pitstop

Pitstop — F1 MCP 服务

一个以 HTTP 为先的一级方程式数据模型上下文协议（MCP）服务。它汇总多个权威来源的实时、历史和新闻数据，提供 11 个工具，可供任意 MCP 客户端使用。

v0.5.0 | 作者：Praneeth Ravuri

---

安装

托管端点（无需安装）

Hugging Face Spaces 上运行着一个免费的公开实例：

https://praneeth1025-pitstop.hf.space/mcp

claude mcp add --transport http pitstop https://praneeth1025-pitstop.hf.space/mcp

注意：Space 长时间无人访问后会进入休眠状态；沉寂一段时间后的首次请求需要冷启动。

本地安装

通过 uvx 使用 stdio（无需克隆）：

PITSTOP_TRANSPORT=stdio uvx pitstop-f1

Claude Code：

claude mcp add pitstop -e PITSTOP_TRANSPORT=stdio -- uvx pitstop-f1

Codex CLI：

codex mcp add pitstop --env PITSTOP_TRANSPORT=stdio -- uvx pitstop-f1

Gemini CLI：

gemini mcp add pitstop uvx pitstop-f1 --env PITSTOP_TRANSPORT=stdio

VS Code：

code --add-mcp '{"name":"pitstop","command":"uvx","args":["pitstop-f1"],"env":{"PITSTOP_TRANSPORT":"stdio"}}'

Claude Desktop（claude_desktop_config.json）、Cursor（~/.cursor/mcp.json）和 Windsurf（~/.codeium/windsurf/mcp_config.json）使用相同的 JSON 格式：

{
  "mcpServers": {
    "pitstop": {
      "command": "uvx",
      "args": ["pitstop-f1"],
      "env": { "PITSTOP_TRANSPORT": "stdio" }
    }
  }
}

Docker（HTTP 传输，运行完整服务，包括 F1 数据库）：

docker compose up
# → http://localhost:8000/mcp

---

概述

Pitstop 通过 HTTP（默认）或 stdio 提供 11 个 MCP 工具，用于获取 F1 数据。它从 FastF1、Jolpica、OpenF1、Wikidata、RSS 源和自带的 F1 数据库中获取数据，并透明地处理分页、重试、缓存和并发限制。

---

数据来源

来源	覆盖范围	类型
FastF1	2018 年至今	历史数据 / 计时 / 遥测
Jolpica-F1	1950 年至今	历史数据（兼容 Ergast）
OpenF1	2023 年至今	实时数据
Wikidata	所有年代	SPARQL 查询
RSS 源（20 个来源）	实时	新闻
Pitstop F1 数据库	1950 年至今	自有 sqlite 数据库（从 F1DB 初始化，每周从 Jolpica 自行更新）+ 单圈时间

数据库更新：.github/workflows/db-update.yml 每周运行一次，将 Jolpica 的最新赛果拉取到自有 F1 数据库中。

---

工具

工具	描述	关键参数
get_session_data	正赛／排位赛结果、单圈时间、天气、车手详情（2018 年至今）	year、gp、session、includes、page、page_size
get_telemetry_data	逐圈赛车遥测数据（速度、油门、刹车、挡位）（2018 年至今）	year、gp、session、drivers、lap_numbers、max_points、page、page_size
get_live_data	实时间隔、进站、车队无线电、赛段、赛事控制、天气、位置、圈数、超车（2023 年至今）	data_types、year、country、session_name、driver_number、compound、flag、category、page、page_size
get_standings	车手和车队锦标赛积分榜（1950 年至今）	year、round、type、driver_name、team_name、page、page_size
get_schedule	赛事日历和赛段安排	year、include_testing、round、event_name、only_remaining、page、page_size
get_reference_data	赛道、车手、车队百科（1950 年至今）	reference_type、year、name、page、page_size
get_f1_news	来自 20 个 RSS 来源的 F1 头条新闻	source、limit、keywords、driver、team、circuit、year、date_from、date_to、page、page_size
get_results	正赛／排位赛／冲刺赛结果、单圈时间、进站数据（1950 年至今）	year、round、result_type、driver、page
get_race_analysis	速度、轮胎退化、赛段摘要、一致性（2018 年至今）	year、gp、session、drivers、analysis_type、page
query_wikidata	使用 SPARQL 查询 Wikidata，获取 F1 传记、职业生涯记录和历史信息	sparql、page、page_size
query_f1_database	对 pitstop 自有 F1 数据库执行只读 SQL 查询（1950 年至今）：成绩、积分榜、车手家族谱系、车队沿革	sql、page、page_size

---

传输方式

HTTP（默认）

uv sync
uv run pitstop
# → http://localhost:8000

MCP 客户端配置：

{
  "mcpServers": {
    "pitstop": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

stdio（可选）

PITSTOP_TRANSPORT=stdio uv run pitstop

MCP 客户端配置：

{
  "mcpServers": {
    "pitstop": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pitstop", "pitstop"],
      "env": { "PITSTOP_TRANSPORT": "stdio" }
    }
  }
}

---

健康 API

端点	用途
GET /health	各来源状态（FastF1、f1db、Jolpica、OpenF1、RSS）
GET /live	存活探测
GET /ready	就绪探测

/health 响应示例：

{
  "version": "0.5.0",
  "overall": "ok",
  "sources": [
    { "name": "fastf1",  "status": "ok", "latency_ms": 2,   "detail": "cache writable" },
    { "name": "f1db",    "status": "ok", "latency_ms": 1,   "detail": "" },
    { "name": "jolpica", "status": "ok", "latency_ms": 134, "detail": "" },
    { "name": "openf1",  "status": "ok", "latency_ms": 98,  "detail": "" },
    { "name": "rss",     "status": "ok", "latency_ms": 210, "detail": "" }
  ]
}

overall 为 "ok"／"degraded"／"down"。HTTP 状态码为 200／207／503。

---

Wikidata SPARQL

query_wikidata 会针对 Wikidata 执行 SPARQL 查询，以获取比赛 API 未涵盖的 F1 传记和历史事实。

仅接受 SELECT 和 ASK 查询（只读）。查询中务必包含 LIMIT。

示例——查找 F1 车手及其出生日期：

SELECT ?driver ?driverLabel ?birthDate WHERE {
  ?driver wdt:P31 wd:Q5 ;
          wdt:P641 wd:Q1968 ;
          wdt:P569 ?birthDate .
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en" }
} ORDER BY DESC(?birthDate) LIMIT 10

---

分页

所有返回列表的工具都接受 page（从 1 开始，默认值为 1）和 page_size（默认值因工具而异：10–50）。响应中包含一个 pagination 块：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 47,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

---

配置

变量	默认值	描述
PITSTOP_TRANSPORT	http	http 或 stdio
PITSTOP_HOST	0.0.0.0	绑定地址（仅 HTTP）
PITSTOP_PORT	8000	监听端口（仅 HTTP）
PITSTOP_ENV	development	development 或 production
PITSTOP_LOG_LEVEL	取决于 PITSTOP_ENV	若为 development，则为 DEBUG；否则为 INFO
PITSTOP_LOG_FORMAT	取决于 PITSTOP_ENV	若为 development，则为 text；否则为 json
PITSTOP_ENABLE_CACHING	true	启用 HTTP 响应和 FastF1 磁盘缓存
PITSTOP_CACHE_TTL_SECONDS	300	HTTP 响应缓存生存时间（秒）
PITSTOP_RATE_LIMIT_ENABLED	false	启用并发调用限制
PITSTOP_RATE_LIMIT_PER_HOUR	3600	最大并发调用数（根据每小时配额推算）
FASTF1_CACHE	cache	FastF1 缓存目录路径

---

缓存

Pitstop 使用内存中的 HTTP 响应缓存（通过 Hishel），缓存返回 200 响应的 GET 请求。这有助于工具调用不超过上游服务的速率限制：

• Jolpica：4 req/s，500/hr
• OpenF1：3 req/s，30/min
• Wikidata：查询复杂度限制
• RSS：缓存每个 Feed 的重定向

FastF1 会在 FASTF1_CACHE 目录中维护自己的磁盘缓存。通过以下选项控制缓存：

• PITSTOP_ENABLE_CACHING=true（默认）
• PITSTOP_CACHE_TTL_SECONDS=300（默认）

---

开发

uv sync --dev
uv run pytest
uv run ruff check src/

---

贡献

请参阅 CONTRIBUTING.md。

---

致谢与归属

来源	描述	许可证
F1DB	从 F1DB 初始化数据库，之后由 pitstop 修改并扩展	CC BY 4.0
FastF1	用于 F1 计时、遥测和比赛阶段数据的 Python 库	MIT
Jolpica-F1	兼容 Ergast 的 F1 数据 API，涵盖 1950 年至今；也用于每周自动更新以 F1DB 初始化的数据库	—
OpenF1	提供实时 F1 数据的免费开源 API	MIT
Wikidata	提供 SPARQL 查询服务的开放知识图谱	CC0
Ergast Motor Racing API	1950–2024 年的 F1 历史数据（现通过 Jolpica 提供）	—
RSS Feeds（20 个来源）	新闻标题，统一致谢；请参阅 get_f1_news 结果中各 Feed 的 link 字段	相应发布者

与 Formula 1 或 FIA 无关联。数据由第三方来源根据各自的条款提供。