sportsdata-mcp

PyPI PyPI downloads

Ask your AI which bookmaker is paying more — and get a real answer.

Free & open source (MIT). ~841 tools across 64 providers in Claude Desktop, Cursor, or any MCP client. uvx sportsdata-mcp serve and you're done.

You: Which book has the best price on Parramatta v Penrith, and how big is the spread?

Claude queries five books at once and comes back with:

Real captured odds. The same bet on Penrith pays $6.20 at Betfair and $4.75 at Sportsbet — a 30% spread on identical risk. That gap is invisible unless something is reading every book at once.

What this one is for: comparing prices, not just fetching scores. Plenty of sports MCP servers will get you fixtures and standings. This one is built around disagreement between books — eleven bookmakers, the Betfair exchange, and two prediction markets (Kalshi, Polymarket) side by side on the same market, plus twenty-seven official league/stats feeds. Deep on AU/NZ books (Sportsbet, TAB, Ladbrokes, PointsBet, BetR, Dabble) and on racing — thoroughbred, greyhound and harness with tote pools and exchange money — which most catalogues skip entirely. Capability tags make providers interchangeable, so "compare odds across books" is one question rather than forty-three integrations.

Is this for you?

Worth being straight about, because it decides whether the first thing you ask works or looks broken.

Best fit — you follow or bet into Australian markets. The cross-book edge above is the reason this exists, and it is built on 159 tools across eight Australian books: Sportsbet, TAB, PointsBet, BetR, Ladbrokes/Neds, Betfair, Dabble, Unibet. Nothing else exposes that, and racing — thoroughbred, greyhound and harness, with tote pools and exchange money — is covered to the same depth.

Also good — you want sport data anywhere in the world. The other 682 tools across 56 providers are not region-locked: MLB, NBA, NFL, NHL, the Premier League, cricket, golf, tennis, F1, UFC, fantasy (ESPN, Sleeper, FPL), plus Pinnacle and the Kalshi and Polymarket prediction markets. 486 of those need no key at all.

Not a fit — you want US sportsbook odds. Those eight books are licensed for Australia and block traffic from outside it. From the US you get Pinnacle, FanDuel, Kalshi and Polymarket for prices; the stats and fantasy side works in full. If cross-book US pricing is what you came for, this is not the tool.

It can now place bets. Read this bit.

Since 0.31.0 the catalogue includes sportsbet_place_bet, tab_place_bet, entain_place_bet and unibet_place_bet. These stake real money from your own account, using credentials you supply. Nothing calls them on its own — they are ordinary tools, so whatever you connect this server to decides when they run.

Two things follow, and neither is optional reading:

• An LLM with these tools in scope can place a bet. If that is not what you want, do not enable the account groups; every other group is unaffected, and list-groups shows exactly what you have turned on.
• Only Sportsbet and TAB have been round-tripped against a real account. Unibet and Ladbrokes/Neds have their request shape captured from placements made in a browser, which proves the request and says nothing about whether a stored credential alone is accepted.

The agent workbench applies its own policy on top of this — everything starts in paper mode and stakes nothing until you opt a book in — but that is the app's guardrail, not this server's. On its own, this package does what it is asked.

Rather than take that on trust, ask it:

sportsdata-mcp coverage

It probes every provider from your machine and prints what answered, what your location blocks, and what needs a key — so an empty result is never ambiguous between "no data" and "wrong country".

Built on this server

Two live terminals, both open source, both running on nothing but these tools:

sportsdata-ai.com/sports — prediction markets + exchange as a de-vigged sharp line, every book measured against it.

sportsdata-ai.com/board — racing money flow: which runners are firming, fair price vs the field, win%/ROI scorecard.

Try these once it's installed

• "Compare head-to-head odds across every book for tonight's NRL games."
• "Which AFL games have the biggest price disagreement between bookmakers?"
• "What does Betfair imply for the Panthers vs what Sportsbet is offering?"
• "Show me Pinnacle's line on every MLB game today."
• "Pull the ladder and last five results for Hawthorn."

An MCP server that exposes sports-data APIs (bookmakers, league/governing-body feeds, aggregators) as tools, configurable so you only load the tool groups you need. A capability-tag system makes tools from different providers interchangeable wherever they answer the same question — so the model can compare odds across bookies or stats across data sources with one discovery call.

The catalogue spans bookmakers, league/governing-body feeds, and stats aggregators, and it keeps growing. New providers are added by dropping a YAML spec into src/sportsdata_mcp/specs/ — the engine needs no code changes — so the exact provider and tool counts move over time. Run sportsdata-mcp list-groups for the live inventory, and three meta-tools (group discovery, capability lookup, resource listing) are always on regardless of what you enable.

Install

One-liner (any MCP client config, via uv):

uvx sportsdata-mcp serve        # or: pip install sportsdata-mcp

Prebuilt app (no Python needed): grab the latest release (macOS + Windows), unzip, and run sportsdata-mcp setup — it writes the config for Claude Desktop / Cursor for you. The macOS build is unsigned for now: right-click → Open the first time.

From source:

git clone https://github.com/DanielTomaro13/sportsdata-mcp.git
cd sportsdata-mcp
pip install -e .                # add ".[dev]" for the test + lint toolchain

Quickstart

sportsdata-mcp version          # print version info
sportsdata-mcp list-groups      # see every available tool group
sportsdata-mcp lint             # validate the packaged specs
sportsdata-mcp doctor           # probe enabled groups for reachability + auth
sportsdata-mcp serve            # start the MCP stdio server (default command)
sportsdata-mcp update-specs     # OTA-refresh provider specs (signed bundle); --clear reverts

Provider endpoints drift (e.g. Entain rotates its GraphQL persisted-query hashes). update-specs fetches a signed spec bundle and applies it into an overlay under ~/.sportsdata/spec-overlay, which the loader prefers over the packaged copy — so a drift fix doesn't need a whole new app build. The bundle is Ed25519-verified against a baked key (a product build refuses an unsigned/forged bundle; anti-rollback refuses a stale replay). Publish one with scripts/publish-spec-bundle.py; point --url / $SPORTSDATA_SPEC_FEED_URL at the asset. Restart the server after applying.

Enable tool groups with a config file or the SPORTSDATA_MCP_GROUPS env var:

SPORTSDATA_MCP_GROUPS="afl.public.core,sportsbet.racing,entain.graphql" sportsdata-mcp serve

See examples/ for Claude Desktop / Claude Code config snippets, a worked cross-bookie odds-comparison prompt, and an NBA shot-chart + box-score walkthrough that shows the nba_stats_call dispatcher pattern end to end.

Configuration

Config is resolved in this order (first hit wins):

1. --config <path> flag
2. $SPORTSDATA_MCP_CONFIG
3. ./sportsdata-mcp.yaml
4. ~/.config/sportsdata-mcp/config.yaml
5. built-in defaults

# sportsdata-mcp.yaml
enabled_groups:
  - afl.public.core
  - sportsbet.racing
  - entain.graphql

providers:                      # all optional; sensible defaults apply
  sportsbet:
    request_timeout_seconds: 30
    rate_limit_rps: 10          # sustained requests/sec (token bucket)
    max_response_bytes: 0       # 0 = no cap (default); set a positive byte count to guard context

secrets: {}                     # for authenticated providers; prefer env vars in prod

A provider whose auth reads env: SOME_VAR is satisfied by the real environment variable first, then by a secrets: { SOME_VAR: "..." } entry of the same name (a local-dev convenience — keep real secrets in the environment in production).

Environment variables

The (dormant) entitlement gate

This project used to be a paid product. It's free now — no licence exists or is needed, and every group serves by default — but the signed-entitlement machinery (Ed25519-verified feed grants, offline caching, 15-min revalidation) is kept dormant rather than deleted: it's tested, harmless when unset, and useful to anyone self-hosting this server who wants to gate premium feeds for their own users. Set SPORTSDATA_LICENSE + SPORTSDATA_ENTITLEMENT_URL against your own issuing service to activate it; leave them unset (the default) and nothing changes.

Keyed feeds. A few providers need an upstream credential you supply yourself — e.g. DATAGOLF_KEY for DataGolf, X_BEARER_TOKEN for Twitter/X. Everything else needs no key at all.

Meta-tools (list_available_groups, list_tools_by_capability, list_resources) are always registered regardless of what is enabled, so a fresh install can still guide the model to turn groups on.

On the response-size cap. There is no cap by default — every tool returns whatever the upstream API sends. If you want to guard the model's context window you can opt in to a cap: precedence is providers.<id>.max_response_bytes > SPORTSDATA_MCP_MAX_BYTES > the default (0, unlimited). Be aware that very large payloads (e.g. Sportsbet's full *_event_markets firehose, ~2 MB) won't fit in Claude's ~200 K-token context regardless — for those, prefer a narrower tool such as sportsbet_sports_card with includeTopMarkets: true.

Tool groups

Run sportsdata-mcp list-groups for live counts and descriptions.

AFL — api.afl.com.au

Sportsbet — sportsbet.com.au

Entain / Ladbrokes — ladbrokes.com.au

PointsBet — pointsbet.com.au

TAB — tab.com.au

Unibet — unibet.com.au

BetR — betr.com.au (BlueBet platform)

Pinnacle — pinnacle.com (sharp odds)

Betfair Exchange — betfair.com.au (exchange odds)

Dabble — dabble.com.au (iOS app backend)

The Australian social-betting app's backend, read directly. Reached by posing as the iOS app — the spec bakes the app's User-Agent + x-device-id + x-app-version so the public feeds return JSON anonymously. AU-only and Cloudflare-fronted (403s from non-AU IPs, like the other AU books). Works for any competition — dabble_active_competitions lists the ~269 currently-bettable ones across all sports. Read-only odds — no bet placement. Composes with the other books via sport.event_markets / sport.prices.

SuperCoach — supercoach.com.au (News Corp / Champion Data fantasy)

News Corp / Champion Data's salary-cap fantasy game. Every feed lives under /{year}/api/{sport}/classic/v1/… — pass sport (one of the seven) and year (the season key: current calendar year for afl/nrl, currently 2025 for the others, which run across the new year). No auth, not geo-blocked (runs in CI). The core supercoach_players feed is per-round and large (~1–3 MB); use ppts1 (the real projection), not ppts. Adds the fantasy / projections angle via stats.fantasy_projections alongside Data Golf. See documentation/SuperCoach.md.

NBL — nbl.com.au (Australian National Basketball League)

The league's own site data API — a Redis-cached proxy ("rosetta") over Genius Sports stats at prod.rosetta.nbl.com.au/get/…. No token, but referer-gated (403s without an nbl.com.au Origin + Referer — both baked into the spec). Every response is enveloped {type, count, source, data:[…]}. Season-scoped by year (the season start year: 2025 = NBL26, current); stat-leaders takes the season UUID from nbl_seasons. Distinct from the SuperCoach nbl fantasy feed — this is the official box-score source. See documentation/NBL.md.

WTA — wtatennis.com (Women's Tennis Association, official)

The WTA's official data API (api.wtatennis.com/tennis/…) — public Spring REST, no auth/key, no geo-block, runs in CI. Rankings need type+metric (rankSingles+singles or rankDoubles+doubles); tournaments are keyed by tournamentGroup.id + year (Australian Open = group 901). Fills the tennis gap on the stats side, composing with the bookmakers' live tennis markets. See documentation/WTA.md. (ATP has no equivalent open API — atptour.com is Cloudflare bot-protected — so it isn't modelled.)

Racing and Sports — racingandsports.com.au

Data Golf — datagolf.com (needs a key)

Needs a Data Golf API key in the DATAGOLF_KEY env var (a personal subscription key — sourced via the static_query auth scheme, never stored in the repo).

FanDuel — fanduel.com (US)

NRL — mc.championdata.com

Plus the nrl://stats/definitions resource (dictionary of every NRL stat code).

NBA — cdn.nba.com + stats.nba.com

nba_stats_call fronts the whole stats.nba.com /stats/ analytics surface (player/team dashboards, box scores v2+v3, shot charts, play-by-play, leaders, standings, draft, hustle, tracking, …). Browse every operation, its required params and its defaults in the nba://stats/operations resource.

ESPN — espn.com JSON feeds

All ESPN tools are parametric over sport + league slugs (e.g. football/nfl, basketball/nba, soccer/eng.1), so the five groups cover every league ESPN carries. Browse each dispatcher's operations in its espn://{site,core,web,cdn}/operations resource.

OpenDota — api.opendota.com (Dota 2 esports, no key)

The catalogue's first esports provider. Sides are Radiant/Dire rather than home/away, and hero stats are paired pick/win counts per skill bracket rather than rates — both documented, both test-pinned. The 4.4 MB pro-player list is deliberately not exposed. See documentation/OpenDota.md.

OpenLigaDB — api.openligadb.de (German football, no key)

Fills the big-five hole — you had the Premier League, La Liga and Serie A but no Bundesliga. Crowd-maintained, so the long tail can lag. Note scores live in matchResults, which holds both half-time and full-time entries. See documentation/OpenLigaDB.md.

EuroLeague — api-live.euroleague.net (basketball, no key)

Completes basketball alongside the NBA and NBL. One letter selects the competition (E/U), season codes are E2024, home/away are local/road, and box scores carry PIR rather than an NBA-style efficiency number. See documentation/EuroLeague.md.

NCAA — ncaa-api.henrygd.me (US college sports, no key)

ESPN already gives you college scores; this adds the NCAA's own polls and conference standings in a normalised shape. A third-party mirror of NCAA.com rather than an official feed. See documentation/NCAA.md.

Fantasy Premier League — fantasy.premierleague.com (official, no key)

The world's most-played fantasy game — 4,085,510 registered squads — and public except for your own squad.

One quirk shapes the whole provider: bootstrap-static is a single 1.37 MB blob whose player rows alone are ~362,000 tokens, with no server-side field selection. Four tools hit that one URL and each return one slice, so fpl_players lands at ~58k tokens instead of being unusable. Nothing is invented or renamed — only removed.

Watch the units: now_cost is tenths of a million (145 = £14.5m), form and the expected-goals family are strings, and team is FPL's own 1-20 id rather than the Premier League's. See documentation/FPL.md.

UFC — ufc.com JSON:API (official, no key)

The obvious source, ufcstats.com, is a dead end — it serves a JavaScript proof-of-work bot challenge with noindex and zero data rows in the HTML, so reading it would mean building bot-detection evasion. ufc.com turns out to be better anyway: it runs Drupal with JSON:API exposed, and athlete_stat carries the same FightMetric dataset, down to the same fightmetric_id identifiers.

48 statistics per fighter — significant strikes split by position (standing/clinch/ground) and target (head/body/leg), takedowns landed/attempted/accuracy/defence, submission and knockdown averages, strikes landed and absorbed per minute, career records by finish method.

Two traps worth knowing: related records never inline (without include=athlete_stat a fighter has no statistics at all), and filters silently return 0 rows on the stat collections rather than erroring — so those parameters are not exposed, and sorting is the leaderboard mechanism instead. Rate-limited to 0.5 rps because robots.txt asks for crawl-delay: 15. See documentation/UFC.md.

Football-Data.co.uk — historical results with closing odds (no key)

The only source here you can backtest against. Every other football provider tells you what happened; this one tells you what the market thought would happen, match by match. Pull a completed season, compare closing prices to results, and you have a CLV baseline to measure today's live sportsbet/pinnacle/betfair prices against.

Published as CSV — the one provider using the engine's response_format: csv, so the model still receives ordinary JSON. See documentation/FootballDataUK.md.

Motorsport beyond F1 — MotoGP, Formula E, NASCAR (no key)

With openf1 (live telemetry) and jolpicaf1 (history), the motorsport preset now covers five series. Each has a structural quirk documented in its page — MotoGP needs a four-level uuid walk, Formula E wraps races but not standings, and NASCAR's results array is unsorted and includes non-starters at position 0, so results[0] is not the winner. See MotoGP.md, FormulaE.md, NASCAR.md.

Jolpica F1 — api.jolpi.ca (F1 history 1950 →, no key)

The community successor to Ergast, deprecated at the end of 2024. Complements openf1 rather than overlapping it: OpenF1 is live telemetry from 2023 onward, Jolpica is every race since 1950. "Who won the 1976 Japanese GP" and "what lap is Verstappen on" are different providers. Responses use Ergast's double MRData envelope and return all values as strings — see documentation/JolpicaF1.md.

Chess — lichess.org + api.chess.com (no key)

Both major chess platforms. Note that ratings are not comparable across them — different pools and formulas — and only Chess.com serves game history as JSON, because Lichess streams its exports as NDJSON. See Lichess.md and ChessCom.md.

Squiggle — squiggle.com.au (AFL prediction models)

Not another results feed — the market of opinions about AFL games, which is the natural counterpart to a bookmaker's price. Pull a round's tips, pull the same games from the books, de-vig the prices, and you're comparing a 41-model consensus against the market. squiggle_ladder also carries swarms, the simulated finishing-position distribution behind each projection. One volunteer's server, so the provider ships an honest contact User-Agent and a deliberately gentle rate limit — see documentation/Squiggle.md.

NHL — api-web.nhle.com (official web API, no key)

The league's own API — the one nhl.com reads (the old statsapi.web.nhl.com is dead). The espn.* groups already answer "what's the NHL score"; this is the depth layer. Two conventions worth knowing: season ids are concatenated years (20242025), and /now paths 307-redirect. See documentation/NHL.md.

Sleeper — api.sleeper.app (fantasy football, fully public)

The other major fantasy platform, and the easier of the two to reach: Sleeper's read API needs no key and no cookie — a league id is enough. Joins espnfantasy on the fantasy.* capabilities, so "show me my league" works across both. The 15 MB player catalogue is deliberately not exposed; draft picks carry player names instead. See documentation/Sleeper.md.

ESPN Fantasy — your own fantasy league

The fantasy platform, not the ESPN scoreboard (that's espn.* above) — one URL per league whose payload is chosen by a repeatable view param, covering all five games (ffl football, flb baseball, fba basketball, fhl hockey, wfba WNBA) via a game param on every tool. Public leagues need no credentials; set ESPN_FANTASY_COOKIE to espn_s2=…; SWID={…} and the same tools reach your private leagues. Fantasy playerIds are ESPN athlete ids, so rosters here join straight to the real-world espn.* feeds. See documentation/ESPNFantasy.md for the view catalogue, the x-fantasy-filter cookbook and the id decoder tables.

OpenF1 — api.openf1.org (Formula 1, no key)

Free, no-auth public REST surface (auth: none). Scope feeds by session_key / meeting_key (both accept the literal latest) and driver_number; discover keys with openf1_sessions / openf1_meetings first.

Cricket Australia — cricket.com.au (no key)

Two no-auth hosts (apiv2.cricket.com.au/web + the Pulselive CMS). The apiv2 endpoints carry jsconfig=eccn:true by default so they return the documented camelCase shape; flow is cricketaustralia_fixtures → cricketaustralia_scorecard?fixtureId= → cricketaustralia_players?playerIds=.

MLB — statsapi.mlb.com (official Stats API, no key)

The official MLB Stats API the MLB-StatsAPI library wraps, read directly (no key) — comprehensive coverage of the public surface. sportId=1 is MLB; discover ids with mlb_teams / mlb_schedule / mlb_player_search, then drill into a game or player. Most tools accept the API's hydrate string to embed related objects in one call.

Premier League — premierleague.com (no key)

The private JSON APIs that power premierleague.com, read directly (no key, no cookies) across three hosts (the SDP stats platform, the editorial/ broadcast api.premierleague.com, and static config on resources.premierleague.com). Underlying data is Opta. Premier League = competition 8; season id is the starting year (2025 = 2025/26). Flow: pl_teams → pl_matches → a match id → pl_match/pl_match_stats; pl_standings for the table. Unofficial/undocumented — respect the ~5 rps rate limit. The SDP wire params (_limit, _sort, kickoff>/kickoff<) are exposed under clean tool names (limit, sort, kickoff_after/kickoff_before).

LaLiga — apim.laliga.com (public key shipped)

The private JSON API behind laliga.com (Azure APIM), read directly. Underlying data is Opta. A public Ocp-Apim-Subscription-Key is shipped as a working default, so it runs out of the box — but the key rotates; override it with LALIGA_SUBSCRIPTION_KEY (env or secrets:) when reads start 401-ing (re-harvest from laliga.com's __NEXT_DATA__). A "subscription" is a season instance (slug laliga-easports-2025 = 2025/26); detail endpoints are keyed by slug. Pairs with the Premier League provider for cross-league football comparison via the shared stats.ladder / sport.fixtures_by_date / stats.player_season tags.

Serie A — api-sdp.legaseriea.it (no auth)

The public SDP JSON API behind legaseriea.it, read directly (no auth). Underlying data is Opta. The Serie A competition id is baked in, so you only ever supply a seasonId (discovered from seriea_seasons; seasonName like 2025/2026). Player stats return identity and ~279 Opta metrics in one call (no squad endpoint), paginated 30/page with category=General|Goalkeeping. Completes the big-three football leagues alongside Premier League + La Liga via the shared stats.ladder / sport.fixtures_by_date / stats.player_season tags.

Kalshi — kalshi.com (prediction markets, no key)

The CFTC-regulated US event-contract exchange. Market data is public — no key required; optionally set KALSHI_API_KEY_ID + KALSHI_PRIVATE_KEY(_PATH) and every request is RSA-signed for Kalshi's higher authenticated rate limits (needs pip install "sportsdata-mcp[kalshi-auth]"). Trading surfaces stay out of scope (read-only provider). Id chain: kalshi_series_list(category) → kalshi_events → kalshi_markets → orderbook/trades/candles by ticker. Prices are dollar-denominated.

Polymarket — polymarket.com (prediction markets, no key, geo-gated)

The largest crypto prediction market. All read endpoints are anonymous — the wallet keys Polymarket's SDKs use are for order placement only (out of scope). ⚠️ Geo-gated: Polymarket drops connections at the network edge from restricted jurisdictions (verified: AU IPs time out on every host) — run from an unrestricted region or VPN. Flow: polymarket_events → a market's clobTokenIds → polymarket_book / polymarket_price_history.

X (Twitter) — api.x.com (needs a Bearer token)

The X API v2 read surface — no anonymous tier, so a Bearer token is required: env X_BEARER_TOKEN first (an operator can ship a deployment-wide token for all its users), then the config secrets: block (each user their own). The env var holds the bare token; the spec adds Bearer . Mind your tier's monthly read cap (twitter_usage); the spec throttles ~0.5 req/s and never auto-retries 429s. Write/user-context surfaces (posting, DMs, follows) are out of scope. Flow: twitter_user_by_username("AFL") → id → twitter_user_tweets; search with X operators ("Storm" lang:en -is:retweet).

Bring your own key

Seventeen providers need a key you sign up for yourself. They are excluded from the free preset and from the default group set, so nothing here changes unless you opt in — set the environment variable and add the group.

export THE_ODDS_API_KEY=...
sportsdata-mcp serve --groups "free,theoddsapi.*"

Two things to know before you rely on these

Their response shapes are documented, not verified. We hold no key for any of them, so the shapes in each spec come from the vendor's own documentation rather than from a live probe. Every one of these tools carries an explicit note telling the model to inspect the payload it actually received rather than trusting the sketch. Elsewhere in this catalogue the shapes were probed and corrected — roughly one in three turned out to differ from what the docs implied — so treat this tier as the lower-confidence one until you have run it with your key. If you do, a PR flipping shapes_verified: true with the corrections is the single most useful contribution available.

Four of them report failures with HTTP 200. apitennis answers a bad key with 200 {"error":"1", …}, cricketdata with 200 {"status":"failure","reason":"Invalid API Key"}, isportsapi with 200 {"code":2,"message":"Invalid [api_key]…"}, and apisports returns 200 with a populated errors object and an empty response when you exhaust the daily quota. That last one is the nastiest: a model asking for today's fixtures gets an empty list and reports "no matches today", so a blown quota is indistinguishable from a quiet Tuesday. All four specs declare error_signals, and the engine raises a real error naming the variable to set. If you consume these APIs outside this server, check the body — the status code will lie to you.

Odds-API.io is /v3/, not /v2/. The vendor's own pages advertise v2 paths; every one of them 404s. Caught by probing before the spec was written — otherwise all five tools would have shipped broken.

Not included

Three candidates were probed and rejected rather than shipped broken:

SportDevs — as of 2026-08-10 sportdevs.com, api.sportdevs.com and rugby.sportdevs.com have no DNS record at all. The service is gone, so the rugby/volleyball/handball coverage it advertised is not available from it. (Rugby union is instead covered by apisports.)

Live Golf API — use.livegolfapi.com resolves, but every path including the root returns 404 {"message":"Application not found"}. The host is up; the application behind it is not deployed.

Fighting Tomatoes — the documented API paths under fightingtomatoes.com/API/… return the site's 404 page. The domain serves a web app, not the API it advertises.

TheSportsDB's free tier returns silently truncated data — an EPL table comes back with 5 rows of 20, with nothing marking it as partial. A provider that quietly answers with a fifth of the table is worse than no provider, so it is excluded rather than shipped with a warning.

Telemetry

Nothing is transmitted unless you turn it on. There is no default that sends, no first-run prompt that defaults to yes, and consent is readable only from an environment variable — never from a config file, because a config file can be committed to a repo or baked into someone else's Docker image.

What IS always on is local recording, which is yours:

sportsdata-mcp stats

Per-tool call counts, error rates, error codes and empty-result counts, worst first. A model can read the same thing mid-session via sportsdata_session_stats — usually the fastest way to tell a missing key (100% errors, code AUTH_REQUIRED) from an upstream with no data (no errors, high empty).

To share it, two deliberate acts are required, and neither alone transmits:

export SPORTSDATA_TELEMETRY=1
export SPORTSDATA_TELEMETRY_ENDPOINT=https://your/collector

Tool arguments are never recorded, and that guarantee is structural rather than a filter: Telemetry.record() has no parameter that could accept them. This matters here more than in most projects — an ESPN Fantasy league id identifies a league and its members, and a Sleeper username is a username.

sportsdata-mcp telemetry --show-payload

prints the exact JSON a transmission would contain, so the claims are checkable rather than promised. Full detail, including what the one free-text field does: docs/TELEMETRY.md.

For adoption numbers that touch no user at all — PyPI downloads, unique cloners, referrers — python scripts/metrics.py reads public data about the package instead.

Cross-provider comparison

Every tool is tagged with provider-agnostic capability slugs (e.g. sport.event_markets, racing.race_card). Tools sharing a slug answer the same question and are directly comparable across providers. The discovery flow:

1. list_tools_by_capability("sport.event_markets") → every enabled tool exposing it
2. Call each provider's tool concurrently with the resolved event ids
3. Compare the raw snapshots (schemas are not normalised — the model reconciles them)

See examples/comparator-prompt.md for a full "compare Storm v Cowboys odds across bookies" walkthrough.

Per-provider notes

• Sportsbet — anonymous public APIs; no secrets needed. REST events are keyed by integer eventId; a persisted-GraphQL gateway is exposed via sportsbet_graphql_call (browse sportsbet://graphql/operations).
• Entain / Ladbrokes — a persisted-GraphQL gateway; the model supplies an operation name + variables (discover them in entain://graphql/operations). Hashes can drift when the front-end bundle ships; refresh them with sportsdata-mcp refresh-hashes entain.
• AFL — afl.public.* is anonymous. afl.premium.* mints an anonymous x-media-mis-token automatically; some premium endpoints still return 401 for anonymous callers.
• NRL — the anonymous Champion Data match-centre CDN (mc.championdata.com), the same static JSON the official nrl.com match centre reads. No secrets, no cache-buster params needed. Resolve a competitionId from nrl_competitions (e.g. 12999 = 2026 NRL Premiership), a matchId from nrl_fixture, then pull per-player match stats from nrl_match; decode stat codes via nrl://stats/definitions.
• NBA — two surfaces, no secrets. cdn.nba.com is wide open (it even serves JSON as text/plain, which the client accepts). stats.nba.com sits behind Akamai, which black-holes any request missing a full browser header bundle — the spec ships that bundle in provider.default_headers, so it just works. Akamai also rate-limits hard, so the spec's defaults block throttles NBA to ~1 req/2.5 s, sets a 45 s timeout, and retries transient 429/5xx with exponential backoff (all overridable via providers.nba.*). The /stats/ family is one dispatcher (nba_stats_call): pick an operation (the path segment, e.g. leaguedashplayerstats) and pass query_params — each operation already carries NBA's full default param set, so you override only what matters. Most responses are column-oriented (resultSets:[{name, headers, rowSet}]}); v3 box scores are nested.
• ESPN — four public hosts, no auth, no API key: site.api.espn.com (scores, teams, standings, news, summaries), sports.core.api.espn.com (the canonical $ref-linked model — odds, win-probability, plays, venues, drafts, coaches), site.web.api.espn.com (search + athlete views) and cdn.espn.com (the live core feed, needs ?xhr=1). Nearly every URL is .../sports/{sport}/{league}/{resource}, so the tools take sport + league as parameters and cover every ESPN league parametrically — NFL, NBA, MLB, NHL, college, soccer (eng.1, esp.1, …), golf, racing, tennis, MMA and more. Discovery: espn_scoreboard(sport, league) → an event id → espn_game_summary or the deep espn_core_call(event_*) ops. The spec throttles to ~5 req/s and retries transient 429/5xx (overridable via providers.espn.*). Note the core API path uses leagues/{league} (plural); core list responses are lazy {count, items:[{$ref}]} envelopes — follow the refs for detail.
• PointsBet — anonymous public APIs, no secrets. api.au.pointsbet.com serves the sportsbook (sports + racing); pointsbet.com.au serves static CMS/nav assets via the pointsbet_content_call dispatcher. Sports discovery: pointsbet_sport_competitions(sportKey) → a competition key → pointsbet_event(eventKey) for the full market book. Racing: pointsbet_racing_meetings(startDate, endDate) → a raceId → pointsbet_racing_race. Many feeds return a top-level JSON array.
• TAB (Tabcorp) — anonymous public data, no secrets. api.beta.tab.com.au sits behind Akamai (the spec ships a browser header bundle + ~2.5 rps throttle, like NBA); cmsapi.tab.com.au serves CMS feeds via tab_cms_call. Every endpoint needs a jurisdiction (defaults to NSW). The API is HATEOAS and name-based — paths embed sport/competition/match/venue names with spaces (…/AFL Football/competitions/AFL/matches/Adelaide v Geelong), which the HTTP layer percent-encodes; pass raw names. Racing: tab_racing_meetings(date) → raceType+venueMnemonic → tab_racing_race. Sports: tab_sport → tab_competition → tab_match for the full market book.
• Unibet — anonymous AU data, no secrets, two surfaces. Racing is persisted-GraphQL (unibet_racing_call, the graphql_persisted dispatcher) at rsa.unibet.com.au — race ids are eventKeys like 202606040200.T.AUS.hawkesbury.1; the endpoint enforces Apollo CSRF so a Content-Type: application/json header is sent. Sport is the Kambi offering API (unibet_kambi_call over *.kambicdn.com, market AU): group tree, events, bet offers, in-play, bet-builder. Browse ops in unibet://{racing,sport}/operations.
• BetR — anonymous AU data, no secrets. BetR runs on the BlueBet platform, so the API is web20-api.bluebet.com.au — a flat REST surface covering racing (next-to-jump, grouped racecards, race cards, form, fluctuations) and sport (event types → categories → markets, SGMs). The betr.com.au Next.js _next/data/{buildHash} blobs are skipped (fragile per-deploy hash; the API serves the same data).
• Racing and Sports — www.racingandsports.com.au racing/form data, no auth. racingandsports_todays_racing (/todays-racing-json-v2) is the verified feed — today's meetings across thoroughbred/harness/greyhound, by country. The site is behind Cloudflare, which whitelists that feed but JS-challenges the other paths from datacenter IPs (they work from a residential/browser IP); the form/fields/ results are HTML pages, and GetOdds needs a per-race token, so only the JSON feeds are modelled.
• Betfair Exchange — anonymous, the open read-only web APIs keyed by the public _ak query param. The crown jewel is betfair_market_prices (ero …/bymarket) — exchange back/lay prices, the sharpest reference odds. Discover market ids by walking betfair_navigation (scan …/bynode, e.g. EVENT_TYPE:7 = Horse Racing) down to MARKET nodes; live scores/details come from the ips in-play service. string_csv id params take a list. (The apieds racing widgets are Cloudflare-gated from datacenter IPs and the appsync GraphQL needs a session, so they're out of scope — racing is covered via navigation→bymarket.)
• Pinnacle — anonymous, no key. The Arcadia "guest" API (guest.api.arcadia.pinnacle.com) — the open feed the web sportsbook reads. Sports only (sharp-odds book, no racing); prices are American odds. Flow: pinnacle_sports → pinnacle_sport_matchups(sportId) → pinnacle_matchup_markets(matchupId). The provider sends Pinnacle's public web-client X-API-Key, which unlocks the full per-sport + per-league matchup lists and the parlay markets.
• FanDuel (US) — anonymous US data, no secrets, two surfaces under one provider. Racing is the first full-query GraphQL provider: fanduel_racing_call POSTs the literal query text (the graphql_query dispatcher kind, sibling to the persisted-hash graphql_persisted), with boilerplate variables (brand/product/device/profile) baked as per-op default_variables — most calls need none, override only what varies ({results: 12}, {trackCode, raceNumber}). Sportsbook is REST (fanduel_sb_call) keyed by the static public _ak web key, region NJ. The two halves need different Origin headers, so the sportsbook dispatcher overrides Origin + x-sportsbook-region over the racing-origin provider default. Browse ops in fanduel://{racing,sportsbook}/operations. (US data — composes with other US sources via capability tags.)

CLI reference

-v / --verbose enables DEBUG logging (and un-silences httpx/httpcore).

Contributing

See documentation/ADDING_A_PROVIDER.md for the full guide, with separate playbooks for adding a bookmaker vs a sports website / data API. In short, adding a provider is a spec-only change in the common case:

1. Write src/sportsdata_mcp/specs/<provider>.yaml (copy an existing spec).
2. Tag each tool with capability slugs from specs/_capabilities.yaml; add a new slug there if none fits (two providers sharing a slug makes them comparable).
3. sportsdata-mcp lint — must pass.
4. sportsdata-mcp doctor (with the new groups enabled) — probes it live.
5. pytest -m "not live" — offline suite; drop the marker filter to run live tests.
6. Add a row to tests/contract/test_api_contracts.py so the new provider's documented response shape is verified live on every PR (see below).

pip install -e ".[dev]"
pytest -m "not live"      # offline suite (the CI gate)
pytest -m contract        # live response-contract checks (see below)
ruff check .

CI

Every push/PR runs three jobs (.github/workflows/ci.yml):

• test — ruff, sportsdata-mcp lint, and the offline suite (pytest -m "not live") across Python 3.11–3.13. The deterministic gate.
• contract — pytest -m contract: live response-contract checks that hit each upstream API and assert it still returns the documented shape (top-level keys, and the documented keys on list items). It is resilient by design — it skips on anything outside our control (network errors, 5xx, 401/403/429, geo-blocks, a missing DATAGOLF_KEY, or an empty feed) and only fails on a genuine shape regression or a broken spec (wrong path/params → 4xx). Bookmaker APIs that geo-block GitHub's runners simply skip there.
• package — builds the wheel and proves the CLI loads the packaged specs from a clean install.

Support this project

sportsdata-mcp is free, MIT-licensed, and has no paid tier — every provider and every tool is in the box. Keeping 62 provider specs working against APIs that change without notice is the ongoing cost. If it saves you time, you can chip in at ko-fi.com/danieltomaro.

Entirely optional, and nothing is gated behind it. Starring the repo, filing a good bug report, or adding a provider spec helps just as much.

License

MIT. Copyright (c) 2026 Daniel Tomaro. Free to use, copy, modify and distribute, with the copyright notice and permission notice retained — see LICENSE.

mcp-name: io.github.DanielTomaro13/sportsdata-mcp