Skip to main content
Glama
Sports Betting Stats MCP

Sports Betting Stats MCP

Understat xG & Shot Data - Football Analytics

constructive_calm--understat-football-analytics
Read-only

Scrape Understat football data for xG, shots, PPDA, player and team season stats, career histories, and fixtures across Big 5 leagues and RFPL. Use it to build match and betting analytics datasets.

Instructions

Understat xG & Shot Data - Football Analytics. Scrapes Understat: player/team season aggregates, per-match xG/PPDA/win-probabilities, shot-level data with x/y coords + xG, situation/formation/game-state breakdowns, player career histories, and fixtures across the Big 5 + RFPL (2014–2025). Multi-season + multi-league in a single run.

When to use: Use for expected goals (xG), shot maps, PPDA and player or team season stats in the Big 5 European leagues and RFPL.

Returns: the run's dataset rows as structured JSON (one row per result), plus the run and dataset IDs for paging the full dataset.

Behavior: starts one run of the Apify Actor "constructive_calm/understat-football-analytics" through Apify's hosted MCP gateway (mcp.apify.com) with your own APIFY_TOKEN; the run uses your Apify account. Read-only: it only reads public web data and changes nothing on the source site. Docs: https://apify.com/constructive_calm/understat-football-analytics

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "mode": "<mode>"
    },
    "name": "constructive_calm--understat-football-analytics"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeYesWhat to scrape. 'league_players' returns per-player season aggregates (xG, xA, xGChain, xGBuildup, etc). 'league_teams' returns team season aggregates (W/D/L, xG, xGA, PPDA, points, xPoints). 'league_matches' returns played-match metadata (xG, win-prob, deep, ppda). 'match_shots' returns every shot with x/y coords, xG, situation, body part, result. 'team_situations' returns long-format breakdowns by situation/formation/game-state/timing/zones. 'player_career' returns one player's full multi-sea…league_players
teamsNoFilter output to specific teams. Applies to league_players, league_teams, league_matches, fixtures, match_shots (league discovery) and team_situations. Names must match Understat's display names — e.g. 'Arsenal', 'Manchester United', 'Real Madrid' (matching is case-insensitive). A name that matches nothing produces a 'team_not_matched' status row with closest-name suggestions instead of failing silently.
dateEndNoRestrict league_players stats to matches on or before this date. Leave empty for none.
leaguesNoOne or more of the six leagues Understat covers. Required for league_*, match_shots (when matchIds is empty), team_situations (when teams is empty), and fixtures.
seasonsNoList of season start years as integers — 2025 = the 2025/26 season. Understat history goes back to 2014. The current season becomes valid automatically once it kicks off in August. Invalid entries are reported in a status row instead of being dropped silently.
matchIdsNoSpecific match IDs to scrape directly (used by match_shots). When set, leagues/seasons are ignored. Find IDs in Understat URLs: /match/{ID}.
dateStartNoRestrict league_players stats to matches on or after this date. Leave empty for none.
playerIdsNoPlayer IDs for player_career mode. Find IDs in Understat URLs: /player/{ID}. Examples: 553 (Messi), 619 (Agüero), 1250 (Salah), 8260 (Haaland).
positionsNoFilter players by position. Only applies to league_players mode (uses Understat's filtered POST endpoint).
maxCostUsdNoHard cap on the run's total billed amount. The actor estimates cost up-front and stops gracefully if the cap is hit mid-run.
maxResultsNoStop emitting after this many dataset rows. 0 = unlimited (subject to maxCostUsd).
nLastMatchesNoFilter player stats to the last N matches. 0 = full season. Only applies to league_players mode.
includeRawJsonNoWhen true, attach the original Understat record under `_raw` on every output row. Useful for power users / debugging. Default off — keeps the dataset light.
minAppearancesNoDrop player rows where games played is below this threshold (client-side filter). 0 = no filter.
proxyConfigurationNoApify proxy. Understat does not block scrapers, but residential proxies help users behind corporate networks. Default = Apify residential.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only and open-world annotations, the description explains that a run is started on the Apify Actor via the hosted MCP gateway using the caller's own APIFY_TOKEN and account. It also states that the operation only reads public web data and returns dataset rows plus run and dataset IDs for paging, which is useful operational context. It does not discuss rate limits or billing beyond the schema's maxCostUsd, so it falls short of the richest behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is organized into clear 'When to use', 'Returns', and 'Behavior' sections, with the core purpose front-loaded. The opening line repeats the tool title and name, which is slightly redundant, but the remaining content is efficient and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a 15-parameter scraper with a very rich input schema and no output schema, the description covers the essential context: what data is returned, how runs are authenticated, and that dataset IDs support paging. It does not document the row-level output shape, but the schema already carries nearly all parameter semantics, so the remaining gap is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 15 parameters are already documented in detail, including mode-specific behavior and required combinations. The description only loosely restates that multi-season and multi-league runs are possible and does not add syntax or format meaning beyond the schema, making the baseline score appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: scraping Understat xG, shot, PPDA, and season aggregate data across the Big 5 and RFPL. It enumerates the data families (player/team aggregates, match xG, shot-level coordinates, career histories, fixtures), which clearly separates it from the sibling odds and player-prop tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear 'When to use' trigger: xG, shot maps, PPDA, and player or team season stats in the covered leagues. It does not name explicit alternatives or when-not-to-use conditions, so the agent must infer that odds-related siblings cover betting lines instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.