esportsodds MCP server

esportsodds

The official Python client for the esportsodds.gg CS2 data API.

Counter-Strike 2 matches and results, team and player stats, tournaments, rankings and a derived market line, returned as plain Python dicts. Standard library only: there is nothing else to install.

Get CS2 match data and stats without scraping HLTV. This package is a client for a paid API; it is not an official HLTV/Valve API.

Install

pip install esportsodds

Python 3.10 or newer. No dependencies.

Try it first, with no account: set ESPORTSODDS_API_KEY to the public sample key eo_sample_public, which reads a fixed sample of past matches. It is shared by everyone and rate-limited per network address. For evaluation; our Terms apply.

No subscription yet? A free sandbox key reads a fixed sample of past matches, so you can build against real responses first. The quickstart below asks for upcoming matches, which are outside the sample, so with either key start with sandbox_tour.py and a tournament id from the guide. Any request outside the sample raises PermissionDeniedError (sandbox_scope), and its message names the events that work.

Quickstart

from esportsodds import Client

client = Client()  # reads ESPORTSODDS_API_KEY from the environment

for match in client.matches.list(status="scheduled", sort="scheduled_at", limit=5).data:
    print(match["scheduled_at"], match["team_a_name"], "vs", match["team_b_name"])

2026-10-08T14:00:00Z Team A vs Team B
2026-10-08T17:30:00Z Team C vs Team D

Every call returns what the API sent, as ordinary dicts and lists. A list call returns a Page (page.data, page.next_cursor, page.has_more, page.meta); a call for one thing returns a dict.

Matches come newest first unless you say otherwise, which is what you want for results. For scheduled matches that order starts with the fixture furthest away, so the quickstart passes sort="scheduled_at" to get the next ones to be played.

Your API key and the plan

There are two plans, billed monthly or yearly and paid up front: Standard is $99 a month for 50,000 requests and Pro is $299 a month for 150,000 requests. A year costs ten months: $990 a year for Standard and $2,990 a year for Pro, two months free. Requests are counted per account, per calendar month (UTC), across every key the account owns. There is no trial. A free sandbox key reads a fixed sample of past matches, up to 2,000 requests in total, with no card; it is not a plan, and current data needs one. Past your plan's requests, calls get a 429 with the code quota_exceeded until the month resets, and this client raises QuotaExceededError without retrying (retrying cannot help). A spent sandbox key gets sandbox_quota_exceeded, raised the same way (it never resets), and a request outside its sample raises PermissionDeniedError (sandbox_scope, not counted).

The bulk export (matches.bulk() and the walkers built on it) has one more limit. On a Standard account that first subscribed on or after 30 October 2026 you may make up to 250 bulk-export requests a month; past that the API answers 429 with bulk_quota_exceeded, which raises QuotaExceededError without retrying and leaves every other call working. Pro has no bulk limit, and a Standard account that first subscribed before that date has none either.

Create a key in your account after you subscribe, then keep it out of your code:

export ESPORTSODDS_API_KEY="eo_live_..."

• The client sends the key only in the Authorization: Bearer header, never in a URL. It shows only the last four characters in repr() and never puts the key in an error message or a log line.
• It talks HTTPS only. Plain http:// is accepted for localhost and other loopback addresses (127.0.0.1, ::1) alone, and redirects are never followed, so a key cannot be sent to a different host.
• Keep the key on your server. A browser or mobile app should call your backend, not the API.
• You can look at real responses before subscribing on the public demo.

Configuration

Environment variable	Meaning
ESPORTSODDS_API_KEY	Your API key, used when api_key is not passed.
ESPORTSODDS_BASE_URL	The API address, used when base_url is not passed.

Client(...) argument	Default	Meaning
api_key	None	Your key. When omitted, ESPORTSODDS_API_KEY is read; with neither, ValueError.
base_url	https://api.esportsodds.gg	The API address. HTTPS only, except localhost and other loopback addresses.
game	"cs2"	The title to query. CS2 is the only one with data today.
timeout	30.0	Seconds to wait for a reply. The bulk export always waits at least 120.
max_retries	3	Retries per call for the failures listed under Errors. 0 turns retries off.
transport	None	Your own HTTP stack: any object with send(TransportRequest) -> TransportResponse.

A Client is safe to share between threads. Use it as a context manager (with Client() as client:) or call client.close() when you are finished: it closes a custom transport that has a close() method (the default one keeps no connections open, so it has nothing to release).

Methods

Every endpoint is one method. {game} is the client's game, and {id} accepts the UUID or, for teams, players and tournaments, the slug.

Call	Endpoint	Returns	What it gives you
client.matches.list()	GET /v1/{game}/matches	Page	Fixtures and results, newest first; filter by status, tournament, team, dates and has, order with sort.
client.matches.bulk()	GET /v1/{game}/matches/bulk	Page	Matches with their maps, stats and more embedded (include=), 25 per request.
client.matches.get(match)	GET /v1/{game}/matches/{id}	dict	One match; include= embeds teams, tournament, odds or sub-resources.
client.matches.maps(match)	GET /v1/{game}/matches/{id}/maps	Page	Map-by-map results.
client.matches.stats(match)	GET /v1/{game}/matches/{id}/stats	Page	Per-player stat lines, whole match and per map.
client.matches.vetoes(match)	GET /v1/{game}/matches/{id}/vetoes	Page	The map pick and ban sequence.
client.matches.rounds(match)	GET /v1/{game}/matches/{id}/rounds	Page	Round-by-round team stats: economy, opening duels, clutches, bomb events.
client.matches.history(match)	GET /v1/{game}/matches/{id}/history	Page	What a match used to say: each change with its value before and after.
client.matches.depth(match)	GET /v1/{game}/matches/{id}/depth	dict	Per-player weapons, grenades, hit groups, duels and flashes.
client.matches.lineups(match)	GET /v1/{game}/matches/{id}/lineups	Page	Each team's listed roster before the match.
client.matches.streams(match)	GET /v1/{game}/matches/{id}/streams	Page	The channels broadcasting a match.
client.odds.list()	GET /v1/{game}/odds	Page	The derived market line, as history or as the current board.
client.teams.list()	GET /v1/{game}/teams	Page	Every team, alphabetically; find one by name with q.
client.teams.get(team)	GET /v1/{game}/teams/{id}	dict	One team.
client.teams.h2h(team, opponent=...)	GET /v1/{game}/teams/{id}/h2h	dict	The head-to-head record between two teams.
client.teams.form(team)	GET /v1/{game}/teams/{id}/form	Page	Recent completed results, newest first.
client.teams.ratings(team)	GET /v1/{game}/teams/{id}/ratings	Page	The team's rating history, one point per match.
client.teams.maps(team)	GET /v1/{game}/teams/{id}/maps	Page	The team's record on each map.
client.teams.round_stats(team)	GET /v1/{game}/teams/{id}/round-stats	dict	Round-level playstyle rates: side win rates, pistols, opening duels.
client.teams.vetoes(team)	GET /v1/{game}/teams/{id}/vetoes	dict	A team's own picks, bans and deciders per map, with a permaban flag.
client.teams.results(team)	GET /v1/{game}/teams/{id}/results	Page	Recent results with every map's score and both teams' ratings going in.
client.teams.rivals(team)	GET /v1/{game}/teams/{id}/rivals	Page	The opponents a team meets most, with the head-to-head and rating gap.
client.teams.roster_history(team)	GET /v1/{game}/teams/{id}/roster-history	Page	The five players fielded in each recent match, with roster changes.
client.teams.players(team)	GET /v1/{game}/teams/{id}/players	dict	The players in the team's newest match with stats, with their last-12-month figures.
client.tournaments.list()	GET /v1/{game}/tournaments	Page	Every tournament, newest first; search by name with q.
client.tournaments.get(tournament)	GET /v1/{game}/tournaments/{id}	dict	One tournament.
client.tournaments.teams(tournament)	GET /v1/{game}/tournaments/{id}/teams	Page	The participating teams, by seed.
client.players.list()	GET /v1/{game}/players	Page	Every player, alphabetically by nickname; search by nickname with q.
client.players.get(player)	GET /v1/{game}/players/{id}	dict	One player.
client.players.career(player)	GET /v1/{game}/players/{id}/stats	dict	A player's career totals and averages.
client.players.performance(player)	GET /v1/{game}/players/{id}/performance	dict	Last-12-month figures over recorded maps, each with its percentile among players with a page.
client.players.maps(player)	GET /v1/{game}/players/{id}/maps	dict	The player's figures on each map they have a recorded map on.
client.players.matches(player)	GET /v1/{game}/players/{id}/matches	Page	Recent completed matches, newest first, with the player's own line.
client.players.teams(player)	GET /v1/{game}/players/{id}/teams	dict	The player's team history as stints.
client.players.weapons(player)	GET /v1/{game}/players/{id}/weapons	dict	Weapon and hit-group totals over the last 12 months.
client.rankings.list()	GET /v1/{game}/rankings	Page	A team or player leaderboard over a rolling three-month window.
client.rankings.history()	GET /v1/{game}/rankings/history	Page	The team board at each of the last weekly marks.
client.rankings.round_stats()	GET /v1/{game}/rankings/round-stats	Page	Round-level figures for the top teams, in board order.
client.maps.list()	GET /v1/{game}/maps	Page	League-wide figures for each competitive map.
client.maps.teams(map)	GET /v1/{game}/maps/{id}/teams	Page	How each team fares on, and chooses around, one map.
client.coverage.list()	GET /v1/{game}/coverage	Page	What data exists and how often it refreshes.
client.model.metrics()	GET /v1/{game}/model/metrics	Page	Transparency metrics for the model line, per market. The model line is coming soon; the list may be empty.
client.ws_token()	POST /v1/{game}/ws-token	dict	A 60-second ticket for the WebSocket. Costs no requests.
client.health()	GET /health	dict	The service status. Needs no key and is never retried.

Filters are keyword arguments named as in the API reference. A list given for a comma-separated filter (has=["rounds", "depth"], include=["maps", "stats"]) is joined for you; a datetime or date is formatted for you (a naive datetime means UTC); an unknown argument raises TypeError instead of being sent. Ids are checked and escaped before they go into a URL.

The odds are our own derived lines (source="eo_market"), not any bookmaker's price. The model line (source="eo_model") is coming soon and is not returned yet.

Pagination, the bulk export and the change feed

List calls return one page and a cursor. Walk them yourself:

page = client.matches.list(status="completed", limit=100)
while True:
    for match in page.data:
        print(match["id"])
    if not page.has_more:
        break
    page = client.matches.list(status="completed", limit=100, cursor=page.next_cursor)

or let the client do it. iter() yields rows, pages() yields pages, and both fetch lazily, one request per page, so stopping early costs nothing more. max_pages is a safety limit; the last page yielded still carries its next_cursor, so a job that stops (or crashes) can resume with cursor=.

for match in client.matches.iter(status="completed", date_from="2026-09-01"):
    print(match["id"])

iter and pages exist on matches, odds, teams, tournaments and players.

The bulk export is the cheap way to pull history: 25 matches per request, each with the sub-resources you ask for embedded, and one request against your allowance per page.

from datetime import date, timedelta

week_ago = date.today() - timedelta(days=7)
rows = client.matches.iter_bulk(
    status="completed", date_from=week_ago, include=["maps", "stats"], max_pages=4
)
for match in rows:
    print(match["id"], len(match["maps"]))

max_pages stops the walk after that many requests. Without it, iter_bulk keeps going until the filter runs out, which for a wide one is the whole history, one request per page. On a Standard subscription with the 250-a-month limit, a long walk stops with bulk_quota_exceeded when the month's requests are used. Walk with pages_bulk() and save each page's next_cursor, and the walk resumes with cursor= after the month resets.

A busy moment answers 503 with a short Retry-After; the client waits and retries for you.

The change feed keeps a local copy current. Give iter_changes the changed_at of the newest row you stored last time and it yields every match that changed since, oldest change first:

from datetime import datetime, timedelta, timezone

since = datetime.now(timezone.utc) - timedelta(hours=1)
newest = since.isoformat()
for match in client.matches.iter_changes(since):
    newest = match["changed_at"]  # rows arrive in changed_at order
    print(match["id"], match["status"])
# Store `newest`; it is the `since` for the next run.

It starts ten minutes before since (overlap=) because a row can become visible shortly after the changed_at it carries, and drops the repeats this causes. A quiet hour costs one request. matches.history(match) and matches.iter_history(match) show what each of those changes was.

Errors

Every error is an EsportsOddsError. A reply with an error status raises an ApiError subclass; branch on the class, or on error.code, never on error.message.

Exception	API code	Status	Retried automatically
AuthenticationError	missing_api_key, invalid_api_key, unauthorized	401	No
PermissionDeniedError	forbidden, sandbox_scope	403	No
NotFoundError	not_found, unknown_game	404	No
NotFoundError	match_merged	308	No: a match id retired by a merge; store the surviving id from err.headers.get("x-merged-into")
InvalidRequestError	invalid_parameter	400	No
InvalidCursorError	invalid_cursor	400	No: start the walk again from the first page
ConflictError	conflict	409	No
RateLimitError	rate_limited	429	Yes, after the Retry-After the API sends
QuotaExceededError	quota_exceeded	429	Never: nothing changes until the month resets
QuotaExceededError	sandbox_quota_exceeded	429	Never: a sandbox key's allowance does not reset
QuotaExceededError	sample_quota_exceeded	429	Never: the public sample key's daily allowance resets at 00:00 UTC
QuotaExceededError	bulk_quota_exceeded	429	Never: a plan's monthly bulk-export allowance resets with the month; other calls still work
ServiceUnavailableError	unavailable	503	Yes, after the Retry-After the API sends
ServerError	internal_error	500	Yes, but at most twice
ApiError	any other	other	Only 502 and 504
TransportError	none: the request never got an answer	none	Yes, with backoff
InvalidResponseError	none: the reply was not the shape the API documents	2xx	No

An unknown path id is a 404 (NotFoundError), not a 400, and an unknown id on a sub-resource such as matches.maps(...) returns an empty page rather than an error.

An ApiError carries status, code, message, request_id, retry_after, headers and body. Quote request_id when you report a problem; it is also in client.last_response.request_id.

from esportsodds import QuotaExceededError, RateLimitError

try:
    client.matches.get("00000000-0000-7000-8000-000000000001")
except QuotaExceededError as error:
    print("out of requests until", error.reset_at)
except RateLimitError as error:
    print("slow down; retry in", error.retry_after, "seconds")

Rate limits and retries

Two limits apply: a per-key token bucket (20 requests a second sustained, bursts of 100) and the monthly allowance of your plan, 50,000 requests on Standard or 150,000 on Pro, per account, shared by all of an account's keys. After every call, client.last_response.rate_limit has the budget the API reported:

info = client.last_response  # None until the first call has been made
if info is not None:
    budget = info.rate_limit
    print(budget.quota_remaining, "of", budget.quota_limit, "left; resets", budget.quota_reset)

The client retries only what is safe to retry, up to max_retries times (3 by default), and logs each retry at INFO on the esportsodds logger:

• A 429 rate_limited or 503 waits the Retry-After the API sent, plus up to half a second of jitter. A wait longer than a minute is raised instead of slept through.
• A 502 or 504 and a network failure back off from half a second, doubling, up to eight seconds, with jitter.
• A 500 is retried at most twice however high max_retries is: the API counts it against your allowance, so each retry spends a request you are paying for.
• A 429 quota_exceeded is never retried, and nothing else is.

Polling is rarely the cheapest design: the change feed and the WebSocket cost far fewer requests. The request budget guide has the numbers.

WebSocket (match updates)

The WebSocket pushes score and odds changes for the matches you subscribe to, and it costs no requests: neither the ticket, nor the connection, nor the messages count against your allowance. Updates arrive when our own collection sees a change, so the socket removes your polling delay but cannot make the data newer than that collection; the guide linked below lists the typical ages.

This package does not open sockets itself (that would need a dependency). It mints the ticket and builds the address; any WebSocket library connects, for example websockets (pip install websockets):

import asyncio
import json

import websockets

from esportsodds import Client

client = Client()


async def watch(match_ids: list[str]) -> None:
    ticket = await asyncio.to_thread(client.ws_token)
    async with websockets.connect(client.ws_url(ticket)) as socket:
        await socket.send(json.dumps({"type": "subscribe", "data": {"match_ids": match_ids}}))
        async for raw in socket:
            frame = json.loads(raw)
            if frame["type"] in ("snapshot", "update"):
                print(frame["match_id"], frame["seq"], frame["type"])


asyncio.run(watch(["00000000-0000-7000-8000-000000000001"]))

• A ticket lasts 60 seconds and is not single-use, so a retry inside that window can reuse it; mint a new one once it has expired. Your key never appears in the socket address.
• A snapshot is the full current state of a match and an update is a change. seq counts up per match; if one is skipped, subscribe to that match again to get a fresh snapshot.
• Reconnect with exponential backoff and jitter, and re-send your subscribe. There is no replay.
• A key may hold five connections at once, so subscribe to many matches on one connection.
• The server pings every 54 seconds; websockets answers for you.

The WebSocket guide lists every frame type.

AI assistants (MCP)

The package includes an MCP (Model Context Protocol) server, so an AI assistant such as Claude or Cursor can answer questions from the API: a team's recent form, the vetoes of a match, a player's career figures. It runs on your machine, reads ESPORTSODDS_API_KEY and only reads data. Each tool call is one request against your allowance, and the list tools ask for 20 rows unless the assistant sets limit.

Add it to your MCP client's configuration (Claude Desktop: claude_desktop_config.json; Cursor: ~/.cursor/mcp.json). With uv installed, uvx fetches the package itself, so there is nothing else to set up:

{
  "mcpServers": {
    "esportsodds": {
      "command": "uvx",
      "args": ["esportsodds", "mcp"],
      "env": {"ESPORTSODDS_API_KEY": "eo_live_..."}
    }
  }
}

Or pip install esportsodds and use esportsodds-mcp as the command, with no args (give its full path, from which esportsodds-mcp, if the client cannot find it). In Claude Code:

claude mcp add --transport stdio --env ESPORTSODDS_API_KEY="$ESPORTSODDS_API_KEY" esportsodds -- uvx esportsodds mcp

The tools are matches_list, matches_get, matches_maps, matches_stats, matches_vetoes, matches_rounds, matches_lineups, odds_list, teams_list, teams_get, teams_h2h, teams_form, teams_maps, teams_results, teams_players, tournaments_list, tournaments_get, tournaments_teams, players_list, players_get, players_career, players_matches, rankings_list and maps_list. Each is one row of the methods table above, with that method's arguments, and the server answers clients of every MCP revision from 2024-11-05 to 2026-07-28.