sportsdata-mcp

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.

Three providers ship today — AFL (api.afl.com.au), Sportsbet, and Entain / Ladbrokes — exposing 101 provider tools across 14 groups, plus 3 always-on meta-tools. New providers are added by dropping a YAML spec into src/sportsdata_mcp/specs/; the engine needs no code changes.

Design notes and roadmap live in PLAN.md.

Install

uvx sportsdata-mcp serve        # run without installing
# or
pip install sportsdata-mcp

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)

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 and a worked cross-bookie odds-comparison prompt.

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

Environment variables

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

NRL — mc.championdata.com

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

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.

CLI reference

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

Contributing

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.

pip install -e ".[dev]"
pytest -m "not live"
ruff check .

License

MIT