@sportmonks-mcp/football

An MCP server that gives Claude direct, structured access to the SportMonks Football API v3. Install it once and Claude can fetch real fixture data, live scores, league standings, player profiles, transfers, odds, predictions, bookmaker data, and World Cup 2026 results without you writing a single line of API integration code. It covers 164 tools spanning every major endpoint — including a dedicated suite of 12 pre-wired tools for the 2026 FIFA World Cup that require no league or season IDs.

Table of Contents

• What Is an MCP Server
• Requirements
• Installation
  • Claude Code (Recommended)
  • Claude Desktop — Windows
  • Claude Desktop — macOS
• Quick Start
• World Cup 2026
• All 164 Tools
  • WC2026 (12)
  • Livescores (3)
  • Fixtures (12)
  • Leagues (8)
  • Seasons (4)
  • Standings (5)
  • Topscorers (2)
  • Teams (5)
  • Players (5)
  • Squads (3)
  • Coaches (5)
  • Referees (5)
  • Venues (4)
  • Transfers (6)
  • Transfer Rumours (5)
  • Statistics (3)
  • News (5)
  • Odds (17)
  • Predictions (6)
  • Markets (4)
  • Bookmakers (6)
  • Match Facts (4)
  • Expected Goals / xG (2)
  • Expected Lineups (2)
  • Team Rankings (3)
  • Team of the Week (3)
  • Rivals (2)
  • Commentaries (2)
  • Schedules (3)
  • Stages (4)
  • Rounds (4)
  • TV Stations (3)
  • Reference (7)
• Includes Reference
• Response Structure
• Fixture State Reference
• TypeScript Types
• App Recipes
• Common Mistakes
• Rate Limiting
• Pagination
• Error Handling
• Development
• License

What Is an MCP Server

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude call external tools during a conversation. When you install this server, Claude gains the ability to call the SportMonks Football API directly — fetching live scores, standings, player data, and more — without you ever having to write API integration code.

The practical benefit: instead of copying fixture data into a prompt, you ask Claude to build a livescore widget and it queries the actual API in real time. Every field name, every response shape, and every pagination cursor comes from real data. Claude generates accurate code because it is working with real responses, not guessing from documentation.

Requirements

• Node.js 18 or higher
• A SportMonks API key — get one at my.sportmonks.com
• Claude Code (claude CLI) or Claude Desktop (desktop app)

Installation

Claude Code (Recommended)

Claude Code registers MCP servers per-project or globally. Use --scope user to make the server available in every Claude Code session.

# Build the server first
npx @sportmonks-mcp/football build

# Register globally (available in all projects)
claude mcp add sportmonks-football \
  --scope user \
  -e SPORTMONKS_API_TOKEN=your_token_here \
  -- node $(npm root -g)/@sportmonks-mcp/football/dist/index.js

Or if you have cloned the repository locally:

# From the repo root — build shared + football
pnpm build

# Register the local build
claude mcp add sportmonks-football \
  -e SPORTMONKS_API_TOKEN=your_token_here \
  -- node /absolute/path/to/packages/football/dist/index.js

Verify registration:

claude mcp list

Remove when no longer needed:

claude mcp remove sportmonks-football

Claude Desktop — Windows

1. Clone the repo and build the extension bundle:

   git clone https://github.com/Daiveedjay/Sportmonks-MCP.git
   cd Sportmonks-MCP
   pnpm install
   cd packages/football && pnpm bundle && mcpb pack

   This creates football.mcpb in packages/football/.
2. Open Claude Desktop
3. Go to Settings → Extensions
4. Click Install Extension and select football.mcpb
5. When prompted, enter your SPORTMONKS_API_TOKEN
6. Restart Claude Desktop

Claude Desktop — macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add the server entry:

{
  "mcpServers": {
    "sportmonks-football": {
      "command": "node",
      "args": ["/absolute/path/to/packages/football/dist/index.js"],
      "env": {
        "SPORTMONKS_API_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Quick Start

Once the server is registered, open a Claude conversation and try these prompts:

List all World Cup 2026 stages with their dates and current status

Get the current Premier League standings table — show position, team, played, won, drawn, lost, GF, GA, GD, points

Get Arsenal's fixtures for the next 30 days with scores and opponent names

Show me every goal event in fixture 19135493 with the scorer name, minute, and score at time of goal

Get the full registered squad for Brazil at World Cup 2026 with each player's position and jersey number

World Cup 2026

The 12 wc2026_* tools are pre-wired to the 2026 FIFA World Cup — you never need to look up or pass a league ID or season ID. The constants (league_id: 732, season_id: 26618) are baked into every tool.

The tournament runs June 11 – July 19, 2026. Format: 48 teams, 12 groups, Round of 32, Round of 16, Quarter-finals, Semi-finals, 3rd Place Final, Final.

| Tool | Description | |------|-------------| | wc2026_get_inplay_livescores | All WC2026 matches currently in play | | wc2026_get_all_livescores | Live + matches starting within 15 minutes | | wc2026_get_latest_updates | Fixtures updated in the last 10 seconds — use for polling | | wc2026_get_fixtures_by_date | All matches on a specific date (YYYY-MM-DD) | | wc2026_get_fixture_by_id | Full details for one match by fixture ID | | wc2026_get_standings | Group stage standings for all 12 groups | | wc2026_get_live_standings | Standings that update in real time during matchdays | | wc2026_get_stages | All stages: Group Stage through Final with dates | | wc2026_get_teams | All 48 participating national teams | | wc2026_get_team_squad | Full squad for a team by team ID | | wc2026_get_topscorers | Golden Boot leaderboard, optionally by stage | | wc2026_get_brackets | Full knockout bracket structure from Round of 32 to Final |

All 164 Tools

All tools accept an optional raw: true parameter. By default, responses are shaped into clean typed objects. Pass raw: true to receive the full unmodified SportMonks API response.

Most list tools accept page: number for pagination. Check pagination.has_more in the response to know if more pages exist.

WC2026 (12 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | wc2026_get_inplay_livescores | includes? | All WC2026 matches currently in play with live scores and minute | | wc2026_get_all_livescores | includes? | All live + pre-kickoff WC2026 matches (within 15 min) | | wc2026_get_latest_updates | includes? | WC2026 fixtures updated in last 10 seconds — polling endpoint | | wc2026_get_fixtures_by_date | date (YYYY-MM-DD), includes? | All WC2026 matches on a given date | | wc2026_get_fixture_by_id | fixture_id, includes? | Full match detail: lineups, events, stats, odds, comments | | wc2026_get_standings | — | Group stage table — all 48 teams, 12 groups | | wc2026_get_live_standings | — | Real-time standings during an active matchday | | wc2026_get_stages | — | Group Stage, R32, R16, QF, SF, 3rd place, Final | | wc2026_get_teams | page? | All 48 national teams with confederation groupings | | wc2026_get_team_squad | team_id, includes? | Full squad roster for a team | | wc2026_get_topscorers | stage_id?, page? | Golden Boot leaderboard, optionally per stage | | wc2026_get_brackets | includes? | Knockout bracket from R32 to Final |

Livescores (3 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_inplay_livescores | includes?, filters? | All in-play fixtures across subscribed leagues | | football_get_all_livescores | includes?, filters? | Live + pre-kickoff fixtures (within 15 min) | | football_get_latest_livescores | includes?, filters? | Fixtures updated in last 10 seconds — efficient polling |

Fixtures (12 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_fixture_by_id | fixture_id, includes?, filters? | Complete match data: lineups, events, stats, odds, venue, referees | | football_get_fixtures_by_multiple_ids | fixture_ids[], includes? | Batch-fetch multiple fixtures in one request | | football_get_fixtures_by_date | date, includes?, filters?, page? | All fixtures on a given date | | football_get_fixtures_by_date_range | start_date, end_date, includes?, filters?, page? | Fixtures in a date range (max 100 days) | | football_get_fixtures_by_team_and_date_range | team_id, start_date, end_date, includes?, page? | Team schedule within a date range | | football_get_fixtures_head_to_head | team1_id, team2_id, includes?, page? | Historical head-to-head results between two teams | | football_get_fixtures_search | query, includes?, page? | Search fixtures by team name or match name | | football_get_fixtures_latest_updated | includes?, filters?, page? | All fixtures updated in the last 2 hours | | football_get_all_fixtures | includes?, filters?, page? | All fixtures in your subscription, paginated | | football_get_upcoming_fixtures_by_market_id | market_id, includes?, filters?, page? | Upcoming fixtures available for a specific betting market | | football_get_upcoming_fixtures_by_tv_station_id | tv_station_id, includes?, filters?, page? | Upcoming fixtures broadcast on a TV station | | football_get_past_fixtures_by_tv_station_id | tv_station_id, includes?, filters?, page? | Past fixtures broadcast on a TV station |

Leagues (8 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_leagues | includes?, page? | All leagues in your subscription with IDs and logos | | football_get_league_by_id | league_id, includes? | League details — enrich with currentSeason, country, stages | | football_get_leagues_live | includes? | Leagues with live fixtures right now | | football_get_leagues_by_date | date, includes? | Leagues with fixtures on a given date | | football_get_leagues_by_country | country_id, includes? | All leagues in a country | | football_get_leagues_by_team | team_id, includes? | All leagues a team participates in | | football_get_leagues_search | query, includes? | Find a league ID by name, e.g. "Premier League" | | football_get_current_leagues_by_team_id | team_id, includes?, filters? | Only the leagues a team is currently active in this season |

Seasons (4 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_season_by_id | season_id, includes? | Season details with stages and rounds | | football_get_seasons_by_team | team_id, includes? | All seasons a team has participated in | | football_get_seasons_search | query, includes? | Find a season ID by name, e.g. "2024/2025" | | football_get_brackets_by_season | season_id, includes? | Knockout bracket for any cup competition |

Standings (5 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_standings_by_season | season_id | Full league table: position, points, W/D/L, GF/GA/GD | | football_get_standings_by_round | round_id | Historical table snapshot after a specific round | | football_get_live_standings_by_league | league_id | Real-time standings during an active matchday | | football_get_all_standings | includes?, filters?, page? | All standings in your subscription, paginated | | football_get_standing_correction_by_season_id | season_id, includes? | Points deductions or additions applied to teams in a season |

Topscorers (2 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_topscorers | season_id, page? | Golden boot leaderboard for any season | | football_get_topscorers_by_stage | stage_id, page? | Top scorers filtered to a specific tournament stage |

Teams (5 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_teams | includes?, filters?, page? | All teams in the database (paginated) — prefer scoped endpoints for large queries | | football_get_team_by_id | team_id, includes? | Team profile: name, logo, country, venue, coaches | | football_get_teams_by_country | country_id, includes?, page? | All teams in a country | | football_get_teams_by_season | season_id, includes?, page? | All teams in a season | | football_get_teams_search | query, includes?, page? | Find a team ID by name, e.g. "Arsenal" |

Players (5 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_player_by_id | player_id, includes? | Player profile: name, position, nationality, stats, trophies | | football_get_players_by_country | country_id, includes?, page? | All players from a country | | football_get_players_search | query, includes?, page? | Find a player ID by name, e.g. "Mbappe" | | football_get_players_last_updated | includes? | Players whose profiles changed in the last 2 hours | | football_get_all_players | includes?, filters?, page? | All players in the database, paginated (very large — use filters) |

Squads (3 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_squad_by_team | team_id, includes?, page? | Current registered squad | | football_get_squad_extended | team_id, includes?, page? | Squad with full player details, positions, nationalities | | football_get_squad_by_team_and_season | team_id, season_id, includes?, page? | Historical squad for a past season |

Coaches (5 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_coach_by_id | coach_id, includes? | Coach profile with nationality and career | | football_get_coaches_search | query, includes?, page? | Find a coach ID by name, e.g. "Pep Guardiola" | | football_get_all_coaches | includes?, filters?, page? | All coaches in the database, paginated | | football_get_coaches_by_country_id | country_id, includes?, filters?, page? | All coaches from a specific country | | football_get_last_updated_coaches | includes? | Coach profiles updated in the last 2 hours |

Referees (5 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_referee_by_id | referee_id, includes? | Referee profile with country | | football_get_referees_by_season | season_id, includes?, page? | All referees in a season | | football_get_referees_search | query, includes?, page? | Find a referee ID by name | | football_get_all_referees | includes?, filters?, page? | All referees in the database, paginated | | football_get_referees_by_country_id | country_id, includes?, filters?, page? | All referees from a specific country |

Venues (4 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_venue_by_id | venue_id | Venue profile: name, capacity, city, surface | | football_get_venues_by_season | season_id, page? | All venues used in a season | | football_get_venues_search | query, page? | Find a venue ID by name, e.g. "Wembley" | | football_get_all_venues | includes?, filters?, page? | All venues in the database, paginated |

Transfers (6 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_transfers_latest | includes?, page? | Most recent transfers across all subscribed leagues | | football_get_transfers_by_team | team_id, includes?, page? | All arrivals and departures for a team | | football_get_transfers_by_player | player_id, includes?, page? | A player's full transfer history | | football_get_transfers_by_date_range | start_date, end_date, includes?, page? | All transfers within a date range | | football_get_all_transfers | includes?, filters?, page? | All transfers in your subscription, paginated | | football_get_transfer_by_id | transfer_id, includes? | Single transfer record by its ID |

Transfer Rumours (5 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_transfer_rumours | includes?, filters?, page? | All rumours — includes probability (LOW/MEDIUM/HIGH) and source | | football_get_transfer_rumour_by_id | rumour_id, includes? | Single rumour by its ID | | football_get_transfer_rumours_between_date_range | start_date, end_date, includes?, filters? | Rumours reported within a date range | | football_get_transfer_rumours_by_team_id | team_id, includes?, filters? | All rumours involving a specific team | | football_get_transfer_rumours_by_player_id | player_id, includes? | All rumours linked to a specific player |

Statistics (3 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_season_stats | season_id, participant_id, type ("players"|"teams") | Player or team stats for a season | | football_get_stage_stats | stage_id | Aggregated stats for a tournament stage | | football_get_round_stats | round_id | Aggregated stats for a matchday round |

News (5 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_prematch_news | season_id | Pre-match previews and editorial content | | football_get_postmatch_news | season_id | Post-match reports and editorial content | | football_get_all_news | includes?, filters?, page? | All news articles in your subscription, paginated | | football_get_news_by_season_id | season_id, includes? | All news for a specific season | | football_get_news_by_team_id | team_id, includes? | All news related to a specific team |

Odds (17 tools)

Standard pre-match odds

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_odds_by_fixture | fixture_id, bookmaker_id?, market_id? | Pre-match betting odds, optionally filtered by bookmaker or market | | football_get_all_odds | includes?, filters?, page? | All pre-match odds, paginated — requires Odds add-on | | football_get_odds_by_fixture_and_bookmaker | fixture_id, bookmaker_id, includes? | Pre-match odds for a fixture from one bookmaker | | football_get_odds_by_fixture_and_market | fixture_id, market_id, includes? | Pre-match odds for a fixture on one market | | football_get_last_updated_odds | includes? | Most recently updated pre-match odds |

Standard inplay odds

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_inplay_odds_by_fixture | fixture_id, bookmaker_id?, market_id? | Live in-play odds for an ongoing fixture | | football_get_all_inplay_odds | includes?, filters?, page? | All inplay odds for live fixtures, paginated | | football_get_inplay_odds_by_fixture_and_bookmaker | fixture_id, bookmaker_id, includes? | Inplay odds for a fixture from one bookmaker | | football_get_inplay_odds_by_fixture_and_market | fixture_id, market_id, includes? | Inplay odds for a fixture on one market | | football_get_last_updated_inplay_odds | includes? | Most recently updated inplay odds |

Premium odds (TXODDS — requires Premium Odds add-on)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_premium_odds | includes?, filters?, page? | All premium odds (120+ bookmakers), paginated | | football_get_premium_odds_by_fixture_id | fixture_id, includes?, filters? | Premium odds for a fixture including full odds history | | football_get_premium_odds_by_fixture_and_bookmaker | fixture_id, bookmaker_id, includes? | Premium odds for a fixture from one bookmaker | | football_get_premium_odds_by_fixture_and_market | fixture_id, market_id, includes? | Premium odds for a fixture on one market | | football_get_updated_premium_odds_between_time_range | start_date, end_date, includes?, filters? | Premium odds updated within a datetime range | | football_get_updated_historical_odds_between_time_range | start_date, end_date, includes?, filters? | Historical premium odds updated within a datetime range | | football_get_all_historical_odds | includes?, filters?, page? | All historical premium odds, paginated |

Predictions (6 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_predictions_by_fixture | fixture_id | AI win/draw/loss probability percentages | | football_get_probabilities | includes?, filters?, page? | All outcome probabilities in your subscription, paginated | | football_get_predictability_by_league_id | league_id, includes? | Predictability score for a league | | football_get_probabilities_by_fixture_id | fixture_id, includes? | Win/draw/loss probabilities for a specific fixture | | football_get_value_bets | includes?, filters?, page? | All value bets in your subscription, paginated | | football_get_value_bets_by_fixture_id | fixture_id, includes? | Value bets for a specific fixture |

Markets (4 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_markets | includes?, filters?, page? | All betting markets with names and IDs | | football_get_all_premium_markets | includes?, filters?, page? | All markets in the Premium Odds feed | | football_get_market_by_id | market_id, includes? | Single market by its ID | | football_get_market_search | query, includes? | Search markets by name, e.g. "Match Winner" |

Bookmakers (6 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_bookmakers | includes?, filters?, page? | All bookmakers in the SportMonks odds feed | | football_get_all_premium_bookmakers | includes?, filters?, page? | All bookmakers in the Premium Odds feed (120+) | | football_get_bookmaker_by_id | bookmaker_id, includes? | Single bookmaker by its ID | | football_get_bookmaker_search | query, includes? | Search bookmakers by name, e.g. "bet365" | | football_get_bookmakers_by_fixture_id | fixture_id, includes? | All bookmakers with odds for a fixture | | football_get_bookmaker_match_id_mappings_by_fixture_id | fixture_id | Bookmaker event IDs for a SportMonks fixture (deep-linking) |

Match Facts (4 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_match_facts_by_fixture | fixture_id | Curated key facts and stats for a match | | football_get_match_facts_by_date_range | start_date, end_date, league_id? | Match facts for all fixtures in a date range | | football_get_all_match_facts | includes?, filters?, page? | All match facts in your subscription, paginated | | football_get_match_facts_by_league_id | league_id, includes?, filters?, page? | Match facts for all fixtures in a specific league |

Expected Goals / xG (2 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_expected_by_team | team_id, includes?, filters? | xG data for a team across fixtures | | football_get_expected_by_player | player_id, includes?, filters? | xG data for a player across fixtures |

Expected Lineups (2 tools)

Premium feature — predicted lineups before the official team sheet is released.

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_expected_lineup_by_team | team_id, includes? | Predicted starting lineup for a team | | football_get_expected_lineups_by_player | player_id, includes? | Fixtures a player is predicted to start in |

Team Rankings (3 tools)

Beta feature — rankings based on SportMonks internal scoring model.

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_team_rankings | includes?, filters?, page? | All team rankings in your subscription, paginated | | football_get_team_rankings_by_team_id | team_id, includes? | Ranking history for a specific team | | football_get_team_rankings_by_date | date, includes?, filters? | Rankings as they stood on a specific date (YYYY-MM-DD) |

Team of the Week (3 tools)

Beta feature.

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_totw | includes?, filters?, page? | All Team of the Week selections, paginated | | football_get_totw_by_round_id | round_id, includes? | Team of the Week for a specific round | | football_get_latest_totw | includes? | Most recent Team of the Week selection |

Rivals (2 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_rivals | includes?, filters?, page? | All teams with their rivals data | | football_get_rivals_by_team_id | team_id, includes? | Traditional rivals for a specific team |

Commentaries (2 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_commentaries | includes?, filters?, page? | All match commentaries in your subscription, paginated | | football_get_commentaries_by_fixture_id | fixture_id, includes? | All commentary entries for a fixture — live text feed |

Schedules (3 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_schedules_by_season_id | season_id, includes?, filters? | Full fixture schedule for a season grouped by round | | football_get_schedules_by_team_id | team_id, includes?, filters? | All fixtures for a team across all competitions this season | | football_get_schedules_by_season_and_team_id | season_id, team_id, includes? | Schedule for a team within a specific season |

Stages (4 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_stages | includes?, filters?, page? | All competition stages across your subscription, paginated | | football_get_stage_by_id | stage_id, includes? | Single stage by its ID | | football_get_stages_by_season_id | season_id, includes?, filters? | All stages for a season — find active stage with is_current: true | | football_get_stages_search | query, includes? | Search stages by name, e.g. "Quarter-final" |

Rounds (4 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_rounds | includes?, filters?, page? | All rounds across your subscription, paginated | | football_get_round_by_id | round_id, includes? | Single round by its ID | | football_get_rounds_by_season_id | season_id, includes?, filters? | All rounds for a season, ordered by date | | football_get_rounds_search | query, includes? | Search rounds by name, e.g. "Matchday 1" |

TV Stations (3 tools)

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_tv_stations | includes?, filters?, page? | All TV stations with broadcaster names and IDs | | football_get_tv_station_by_id | tv_station_id, includes? | Single TV station by its ID | | football_get_tv_stations_by_fixture_id | fixture_id, includes? | All broadcasters airing a specific fixture |

Reference (7 tools)

These tools help you write correct code against the API. Call them once and cache the results.

| Tool | Key Parameters | Description | |------|---------------|-------------| | football_get_all_types | — | All type definitions (event types, stat types, lineup types) | | football_get_all_states | — | All fixture states with IDs and codes | | football_get_state_by_id | state_id | Single fixture state by its ID | | football_get_type_by_entity | entity | All type definitions scoped to one entity (player, team, fixture, etc.) | | football_get_entity_schema | entity | Field list, includes, and code patterns for: fixture | standing | player | team | league | transfer | | football_get_types_map | — | Type IDs mapped to names — cache and use to decode type_id fields | | football_get_states_map | — | State IDs mapped to codes — use to decode state_id fields |

Includes Reference

The includes parameter enriches a response with related data in a single API call. Pass an array of strings to any tool that accepts includes.

// Multiple top-level includes — separate array entries
includes: ["participants", "scores", "events", "state", "periods"]

// Nested include — adds the type object inside each statistic
includes: ["statistics.type"]

// Add full player objects to lineup entries
includes: ["lineups.player"]

Do not join multiple top-level includes with dots. Use separate array entries. Dots are only for nesting one entity inside another.

Fixture includes

| Include | Adds | Key fields | |---------|------|------------| | participants | participants[] | id, name, short_code, image_path, meta.location ('home'|'away'), meta.winner | | scores | scores[] | score.goals, score.participant ('home'|'away'), description ('CURRENT', '1ST_HALF', '2ND_HALF', ...) | | state | state object | id, state, name, short_name, developer_name | | periods | periods[] | ticking (bool), minutes, seconds, description, counts_from | | events | events[] | type_id, player_name, minute, extra_minute, result, addition | | lineups | lineups[] | player_id, player_name, team_id, type_id (11=XI, 12=bench), jersey_number, formation_field | | statistics | statistics[] | type_id, participant_id, data.value, location ('home'|'away') | | formations | formations[] | formation (e.g. '4-3-3'), location | | venue | venue object | name, city_name, capacity, surface, image_path | | referees | referees[] | Referee assignment pivot rows | | odds | odds[] | Pre-match odds | | inplayOdds | inplayOdds[] | Live in-play odds | | predictions | predictions object | home_win, draw, away_win percentages | | comments | comments[] | Live commentary: comment, minute, is_goal | | ballCoordinates | ballCoordinates[] | Ball position x, y (0–100 scale), timer | | weatherReport | weatherReport object | temperature, description, humidity, clouds | | xGFixture | xG data | Expected goals per team |

Standings includes

| Include | Adds | |---------|------| | participant | Full Team object on each standing row | | details | details[] array — statistical breakdown keyed by type.developer_name | | form | form[] array — recent results as 'W', 'D', or 'L' |

Response Structure

Default (shaped) response

{
  "id": 19135493,
  "name": "Arsenal vs Chelsea",
  "starting_at": "2026-04-20 16:30:00",
  "status": "FT",
  "minute": null,
  "state_id": 5,
  "league_id": 8,
  "season_id": 23614
}

Raw response (raw: true)

{
  "data": {
    "id": 19135493,
    "name": "Arsenal vs Chelsea",
    "starting_at": "2026-04-20 16:30:00",
    "state_id": 5,
    "participants": [ "..." ],
    "scores": [ "..." ]
  },
  "rate_limit": {
    "remaining": 2843,
    "resets_in_seconds": 1847,
    "requested_entity": "Fixture"
  }
}

Pagination object

All list endpoints include a pagination field alongside data:

{
  "data": [ "..." ],
  "pagination": {
    "has_more": true,
    "current_page": 1,
    "per_page": 25
  },
  "rate_limit": {
    "remaining": 2843,
    "resets_in_seconds": 1847,
    "requested_entity": "Fixture"
  }
}

Fixture State Reference

| ID | Name | Code | Description | |----|------|------|-------------| | 1 | Not Started | NS | Pre-kickoff | | 2 | 1st Half | INPLAY_1ST_HALF | LIVE | | 3 | Half-Time | HT | LIVE | | 4 | Regular Time Finished | BREAK | LIVE — awaiting extra time | | 5 | Full-Time | FT | Finished after 90 min | | 6 | Extra Time | INPLAY_ET | LIVE | | 7 | Finished After ET | AET | Finished after 120 min | | 8 | Full-Time After Pens | FT_PEN | Finished after penalties | | 9 | Penalty Shootout | INPLAY_PENALTIES | LIVE | | 10 | Postponed | POSTPONED | Moved to another date | | 11 | Suspended | SUSPENDED | Will continue later | | 12 | Cancelled | CANCELLED | Permanently cancelled | | 13 | TBA | TBA | No confirmed date | | 14 | Walk Over | WO | No opponent | | 15 | Abandoned | ABANDONED | Will resume | | 16 | Delayed | DELAYED | Kick-off delayed | | 17 | Awarded | AWARDED | Winner decided administratively | | 18 | Interrupted | INTERRUPTED | Temporarily stopped | | 19 | Awaiting Updates | AWAITING_UPDATES | Data delay | | 20 | Deleted | DELETED | No longer active | | 21 | Extra Time Break | EXTRA_TIME_BREAK | LIVE — between ET halves | | 22 | 2nd Half | INPLAY_2ND_HALF | LIVE | | 25 | Penalties Break | PEN_BREAK | Awaiting penalties | | 26 | Pending | PENDING | Awaiting verification |

Live state IDs: [2, 3, 4, 6, 9, 21, 22, 25]

const LIVE_STATE_IDS = [2, 3, 4, 6, 9, 21, 22, 25]
const isLive = LIVE_STATE_IDS.includes(fixture.state_id)

TypeScript Types

All types are exported from @sportmonks-mcp/shared:

import type {
  Fixture, FixtureParticipant, FixtureEvent,
  Score, Period, Lineup, Statistic, Formation,
  Team, Player, Coach, Referee,
  League, Season, Stage, Round,
  Standing, StandingDetail, StandingDetailType,
  SquadEntry, Transfer, Topscorer,
  Venue, Country, State, TypeEntity,
  MatchFact, NewsArticle, Odd, Prediction,
  Bracket, BracketStage, BracketFixture, BracketEdge,
  EntityStatistic,
} from '@sportmonks-mcp/shared'

Shaped response types (default tool responses):

import type {
  ShapedFixture,   // Fixture + { status: string | null, minute: number | null }
  ShapedTeam,      // { id, name, short_code, country_id, logo }
  ShapedPlayer,    // { id, name, common_name, position_id, nationality_id, image_path }
  ShapedStanding,  // { position, team_id, team_name, team_short_code, team_logo,
                   //   points, played, won, draw, lost, goals_for, goals_against, goal_difference }
} from '@sportmonks-mcp/shared'

App Recipes

Livescore widget (polling)

// Initial load
const live = await wc2026_get_inplay_livescores({
  includes: ['participants', 'scores', 'state', 'periods']
})

for (const fixture of live.data) {
  // Home and away teams — NEVER use fixture.home_team
  const home = fixture.participants.find(p => p.meta.location === 'home')
  const away = fixture.participants.find(p => p.meta.location === 'away')

  // Current score
  const current = fixture.scores.filter(s => s.description === 'CURRENT')
  const homeGoals = current.find(s => s.score.participant === 'home')?.score.goals ?? 0
  const awayGoals = current.find(s => s.score.participant === 'away')?.score.goals ?? 0

  // Current minute
  const activePeriod = fixture.periods?.find(p => p.ticking === true)
  const minute = activePeriod?.minutes ?? null
}

// Poll every 10 seconds — only returns changed fixtures
const updates = await football_get_latest_livescores({
  includes: ['scores', 'state', 'periods']
})

Match detail page

const fixture = await football_get_fixture_by_id({
  fixture_id: 19135493,
  includes: [
    'participants', 'scores', 'events', 'lineups',
    'statistics', 'state', 'periods', 'venue',
    'referees', 'formations'
  ]
})

// Goals (14=goal, 15=own goal, 16=penalty scored)
const goals = fixture.events.filter(e => [14, 15, 16].includes(e.type_id))

// Cards (19=yellow, 20=red, 21=yellow-red)
const cards = fixture.events.filter(e => [19, 20, 21].includes(e.type_id))

// Substitutions (18=substitution)
const subs = fixture.events.filter(e => e.type_id === 18)

// Starting XI sorted by formation position
const startingXI = fixture.lineups
  .filter(l => l.type_id === 11)
  .sort((a, b) => (a.formation_position ?? 0) - (b.formation_position ?? 0))

// Home possession % (type_id 45)
const possession = fixture.statistics.find(
  s => s.type_id === 45 && s.location === 'home'
)?.data.value

League standings table

// 1. Find the league
const leagues = await football_get_leagues_search({ query: 'Premier League' })
const leagueId = leagues.data[0].id

// 2. Get current season standings
// ShapedStanding has flat fields — no need to dig through details[]
const standings = await football_get_standings_by_season({
  season_id: leagues.data[0].currentseason.id
})

standings.data
  .sort((a, b) => a.position - b.position)
  .forEach(row => {
    console.log(
      row.position, row.team_name,
      row.played, row.won, row.draw, row.lost,
      row.goals_for, row.goals_against, row.goal_difference,
      row.points
    )
  })

Team profile page

// 1. Find the team
const { data: teams } = await football_get_teams_search({ query: 'Arsenal' })
const teamId = teams[0].id

// 2. Full team profile
const team = await football_get_team_by_id({
  team_id: teamId,
  includes: ['country', 'venue', 'coaches']
})

// 3. Current squad
const squad = await football_get_squad_extended({ team_id: teamId })

// 4. Upcoming fixtures
const schedule = await football_get_fixtures_by_team_and_date_range({
  team_id: teamId,
  start_date: '2026-04-12',
  end_date: '2026-05-12',
  includes: ['participants', 'scores', 'state']
})

// 5. Transfer history
const transfers = await football_get_transfers_by_team({
  team_id: teamId,
  includes: ['player', 'fromTeam', 'toTeam']
})

WC2026 full data load

// 1. Tournament structure
const stages = await wc2026_get_stages()

// 2. All 48 teams (paginated — 2 pages of 25)
const p1 = await wc2026_get_teams({ page: 1 })
const p2 = await wc2026_get_teams({ page: 2 })
const allTeams = [...p1.data, ...p2.data]

// 3. Group standings
const standings = await wc2026_get_standings()

// 4. Today's schedule
const today = new Date().toISOString().split('T')[0]
const todayFixtures = await wc2026_get_fixtures_by_date({
  date: today,
  includes: ['participants', 'scores', 'state']
})

// 5. Knockout bracket (once R32 begins)
const bracket = await wc2026_get_brackets()

Common Mistakes

Using fixture.home_team — this field does not exist

// WRONG — these fields do not exist on the fixture object
const home = fixture.home_team
const away = fixture.away_team

// CORRECT — requires includes: ['participants']
const home = fixture.participants.find(p => p.meta.location === 'home')
const away = fixture.participants.find(p => p.meta.location === 'away')

Joining multiple top-level includes with dots

// WRONG — treats 'scores' as a nested include inside 'participants'
includes: ['participants.scores']

// CORRECT — separate array entries for top-level includes
includes: ['participants', 'scores', 'events']

// Dots are only for true nesting — adds player objects inside lineup entries
includes: ['lineups.player']

Including .type on statistics in production

// WRONG — fetches a type object with every statistic row; wastes rate limit
includes: ['statistics.type']

// CORRECT — fetch all types once at startup and cache
const types = await football_get_types_map()
// Decode in code: types[statistic.type_id].name

Reading score without filtering by description

// WRONG — may pick up 1ST_HALF or 2ND_HALF records instead of current score
const homeGoals = fixture.scores.find(s => s.score.participant === 'home')?.score.goals

// CORRECT — filter to the CURRENT score record
const current = fixture.scores.filter(s => s.description === 'CURRENT')
const homeGoals = current.find(s => s.score.participant === 'home')?.score.goals ?? 0

Displaying player.name in UI

// OK but returns the full legal name ("Kylian Mbappé")
const label = player.name

// CORRECT for UI — uses the preferred display name ("Mbappe")
const label = player.display_name

Rate Limiting

Rate limits are per entity per hour, not per endpoint. /fixtures, /livescores/inplay, and /fixtures/date/{date} all count toward the same Fixture limit.

| Plan | Requests / entity / hour | |------|--------------------------| | Starter | 2,000 | | Growth | 3,000 | | Pro | 2,500 | | Enterprise | 5,000 |

Key strategies:

• Use includes — one request with includes: ['events', 'lineups', 'statistics'] instead of three separate calls
• Poll football_get_latest_livescores instead of football_get_inplay_livescores — only returns fixtures that actually changed
• Poll at 10-second intervals maximum — not 1–2 seconds
• Cache reference data — call football_get_types_map and football_get_states_map once at startup, not on every request
• Use filters — filters: { fixturestatisticTypes: '45,42,86' } returns only the stat types you need

When rate_limit.remaining drops below 100, slow down. When it hits 0, wait rate_limit.resets_in_seconds before retrying. Different entities have independent limits — hitting the Fixture limit does not affect the Team limit.

Pagination

All list endpoints return a pagination field alongside data:

{
  data: [...],
  pagination: {
    has_more: boolean,    // true if more pages exist
    current_page: number, // starts at 1
    per_page: number      // default 25, max 100 for most endpoints
  }
}

Iterate all pages:

let page = 1
const allResults = []

while (true) {
  const result = await football_get_players_by_country({ country_id: 462, page })
  allResults.push(...result.data)
  if (!result.pagination.has_more) break
  page++
}

Error Handling

The server maps SportMonks HTTP errors to readable messages:

| Code | Message | Fix | |------|---------|-----| | 401 | Invalid API token. Check your SPORTMONKS_API_TOKEN. | Verify the token in your MCP server config | | 403 | Your plan does not include access to this endpoint. | Check my.sportmonks.com/subscriptions | | 404 | No data found for this request. | Verify the ID exists — the entity may not be in your subscription | | 422 | Invalid parameters. Check your includes and filters syntax. | Review include names and key:value filter format | | 429 | Rate limit exceeded. Check the rate_limit field in recent responses. | Wait rate_limit.resets_in_seconds then retry | | 500 | SportMonks API is having issues. Try again shortly. | Transient error — retry after a few seconds |

Development

Clone and install

git clone https://github.com/Daiveedjay/Sportmonks-MCP.git
cd Sportmonks-MCP
pnpm install

Build

# Build everything (shared + football)
pnpm build

# Bundle football server (inlines all deps via esbuild — required for Claude Desktop)
cd packages/football && pnpm bundle

Test

# Run all 42 tests across both packages
pnpm test

# With coverage report
pnpm test:coverage

Package for Claude Desktop

cd packages/football

mcpb validate manifest.json   # Validate the manifest
mcpb pack                      # Create football.mcpb
mcpb info football.mcpb        # Inspect bundle contents

Add a new tool

1. Create or extend a file in packages/football/src/tools/football/
2. Import sportmonksGet from @sportmonks-mcp/shared
3. Write the async handler following the existing pattern (accepts includes?, filters?, raw?)
4. Import and register in server.ts with server.tool(name, description, zodSchema, handler)
5. Run pnpm bundle from packages/football
6. Re-register with claude mcp remove then claude mcp add

License

MIT — © 2026 David Jaja

See LICENSE for full text.