fastf1-mcp

FastF1 라이브러리를 통해 AI 어시스턴트에게 포뮬러 1 데이터를 제공하는 MCP 서버입니다. Claude(또는 모든 MCP 호환 클라이언트)에게 레이스 결과, 랩 타임, 텔레메트리, 순위 등에 대해 질문해 보세요.

기능

순위, 레이스 결과, 랩 타임, 텔레메트리, 피트 스톱 및 예선을 다루는 21개의 도구
일정, 드라이버, 컨스트럭터 및 서킷 참조 데이터를 위한 4개의 MCP 리소스
레이스 요약, 예선 분석, 전략 심층 분석 및 주말 프리뷰를 위한 5개의 가이드 프롬프트
비동기 안전 LRU 세션 캐시 — 첫 로드 후 반복 쿼리는 즉시 처리됨
거리 기반 텔레메트리 샘플링 — 대규모 원시 데이터셋을 ≤ 500개 포인트로 압축
모든 오류는 구조화된 딕셔너리로 반환 — 잘못된 입력으로 인해 서버가 중단되지 않음

요구 사항

Python 3.12+
uv (권장) 또는 pip

설치

uv 사용 (권장)

git clone https://github.com/yourname/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**에서 인스펙터를 엽니다.

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_LOG_LEVEL`	`INFO`	Python 로깅 레벨

도구

빠른 조회 (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`	각 드라이버의 베스트 섹터 타임 및 이론상 베스트 랩을 가져옵니다.

유틸리티

도구	설명
`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`	시즌 수준의 1대1 비교: 순위, 레이스, 예선
`strategy_analysis`	`year, event`	스틴트 + 피트 타이밍 + 레이스 페이스 — 전략 싸움의 승자를 설명합니다
`weekend_preview`	`year, event`	서킷 세부 정보 + 최근 기록 + 챔피언십 맥락

예시 쿼리 (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")

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 라이브 타이밍	2018년 – 현재	랩 타임, 텔레메트리, 예선, 피트 스톱, 타이어 데이터

참고: FastF1 세션 데이터는 2018년부터만 제공됩니다. 이전 시즌은 get_race_results_historical을 사용하세요.

라이선스

MIT

fastf1-mcp-server