pyrox-client

HYROX race results as data. A Python client and a public MCP server for analysing them, either in code or by asking an AI assistant.

1.2M+ race results · 316 races · 134 locations · seasons 1–9 (2018–2026), free and MIT licensed, with no API key to sign up for.

https://github.com/user-attachments/assets/2756c10f-166b-45ba-aa3d-089e1f40fe00

Two ways in:

• Ask an AI. Connect the MCP server and query the dataset in plain English, e.g. "where would a 62-minute open time rank in season 8?"
• Write Python. Pull a full race as a pandas DataFrame with splits already converted to minutes, cached on disk so reruns are cheap.

Independent project, not affiliated with or endorsed by HYROX.

Ask an AI (MCP server)

There's a public, read-only MCP server at https://pyrox-api.fly.dev/mcp/. Point Claude, Codex, or any MCP client at it and ask about distributions, rankings, athlete profiles, or a split-by-split race report. The assistant picks the right tool for the question on its own.

# Claude Code
claude mcp add --transport http pyrox https://pyrox-api.fly.dev/mcp/

# Codex
codex mcp add pyrox --url https://pyrox-api.fly.dev/mcp/

Using Claude web or Desktop? No install needed; add it as a custom connector. The MCP guide has the steps, the full tool list, and example prompts. If you connect a Strava MCP alongside it, you can ask the agent to check your splits against the effort your Strava data actually shows.

Use it in Python

pip install pyrox-client

import pyrox

client = pyrox.PyroxClient()

london = client.get_race(season=7, location="london", gender="male")
print(london["total_time"].describe())

# Find what's available first
client.list_seasons()
client.list_locations(season=8)

Station and run columns come back with readable names, already in minutes, so you can drop them straight into a stats workflow. See docs/api.md for the full reference.

Core API

• list_races(season=None), list_seasons(), list_locations(...), list_years(...)
• get_race(season, location, year=None, gender=None, division=None, total_time=None)
• get_season(season, locations=None, gender=None, division=None)
• get_athlete_in_race(season, location, athlete_name, ...)
• clear_cache(pattern="*"), cache_info()

Mistype a location and RaceNotFound hands back the closest matches instead of a bare error.

Reporting helpers (optional)

For heavier local analysis over a DuckDB file, install the extra:

pip install "pyrox-client[reporting]"

The database artifact isn't bundled; you point ReportingClient at a local path. Details in docs/api.md.

Documentation

• Live docs: https://vmatei2.github.io/pyrox-client/
• What's in the dataset: coverage, the full column schema, how often it updates, and the licence
• MCP guide, client API, filters, and the error model live under docs/
• Background write-up: Pyrox MCP server on Medium

Maintaining or releasing? See docs/maintainers/.

License

MIT. Free to use, modify, and distribute. © 2026 Vlad Matei.