io.balldontlie/mcp

Official

by balldontlie-api · TypeScript

Provides access to live sports data and analytics from BALLDONTLIE: The Sports API

Access live sports data and analytics from the BALLDONTLIE Sports API.

BALLDONTLIE Sports MCP Server

A Model Context Protocol (MCP) server that provides access to comprehensive sports data from the BALLDONTLIE API, including NBA, WNBA, NFL, MLB, EPL, NHL, NCAAF, NCAAB, MMA, CS2, League of Legends, Dota 2, FIFA World Cup 2026, La Liga, Serie A, UEFA Champions League, Bundesliga, and Ligue 1 statistics, player information, game data, and more.

Features

250+ Sports Endpoints: Complete access to all BALLDONTLIE API endpoints
18 Major Sports/Leagues: NBA, WNBA, NFL, MLB, EPL, NHL, NCAAF, NCAAB, MMA, CS2, League of Legends, Dota 2, FIFA World Cup 2026, La Liga, Serie A, UEFA Champions League, Bundesliga, Ligue 1
Comprehensive Data: Teams, players, games, statistics, standings, injuries, betting odds, and advanced analytics
Authentication: Seamless API key forwarding to backend
Pagination: Full support for cursor-based pagination
Error Handling: Proper error forwarding and handling
TypeScript: Full type safety and IntelliSense support

Installation

bash

npm install @balldontlie/mcp-server

Quick Start

1. Get API Key

2. Configure MCP Client

Option A: Use Hosted Remote Server (Recommended)

Add to your MCP client configuration (e.g., the agent Desktop) to use the hosted server:

json

{
  "mcpServers": {
    "balldontlie-api": {
      "url": "https://mcp.balldontlie.io/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "<YOUR_BALLDONTLIE_API_KEY>"
      }
    }
  }
}

Replace <YOUR_BALLDONTLIE_API_KEY> with your actual API key from BALLDONTLIE.

Option B: Run from Source

Clone and run from source code:

bash

git clone https://github.com/balldontlie-api/mcp-server.git
cd mcp-server
npm install
npm run build
npm start

Configure your MCP client to connect to the local server:

json

{
  "mcpServers": {
    "balldontlie-api": {
      "url": "http://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "<YOUR_BALLDONTLIE_API_KEY>"
      }
    }
  }
}

3. Use in Your MCP Client

The server will automatically provide all available tools. You can ask your AI assistant things like:

"Get the current NBA standings"
"Show me LeBron James' season stats"
"What are today's NFL games?"
"Get Manchester United's recent EPL matches"
"Show me A'ja Wilson's WNBA season stats"
"What are the current WNBA standings?"
"Show me the NCAAB tournament bracket"
"Get betting odds for tonight's NBA games"

Environment Variables

Variable	Default	Description
`PORT`	`3000`	Server port when running locally
`BACKEND_API_URL`	`https://api.balldontlie.io`	BALLDONTLIE API base URL
`API_TIMEOUT`	`30000`	Request timeout in milliseconds
`LOG_LEVEL`	`info`	Logging level (error, warn, info, debug)
`NODE_ENV`	`development`	Environment (development, production, test)
`ENABLE_DEBUG`	`false`	Enable debug logging
`ENABLE_TRACING`	`false`	Enable DataDog APM tracing (requires DD_AGENT_HOST)
`DD_AGENT_HOST`	-	DataDog agent hostname for APM tracing
`DD_PROFILING_ENABLED`	`false`	Enable DataDog profiling
`SERVICE_VERSION`	`1.0.0`	Service version for tracing

Available Tools

NBA (23 tools)

Tool	Description	Parameters
`nba_get_teams`	Get all NBA teams	`division`, `conference`
`nba_get_team_by_id`	Get specific NBA team	`id` (required)
`nba_get_players`	Get NBA players with filters	`search`, `first_name`, `last_name`, `team_ids`, `player_ids`, pagination
`nba_get_player_by_id`	Get specific NBA player	`id` (required)
`nba_get_active_players`	Get active NBA players	Same as `nba_get_players`
`nba_get_games`	Get NBA games	`dates`, `seasons`, `team_ids`, `postseason`, `start_date`, `end_date`, pagination
`nba_get_game_by_id`	Get specific NBA game	`id` (required)
`nba_get_stats`	Get NBA statistics	`dates`, `seasons`, `team_ids`, `player_ids`, `game_ids`, `postseason`, pagination
`nba_get_season_averages`	Get season averages	`season` (required), `category` (required), `type` (required), `player_ids`, `season_type`
`nba_get_advanced_stats`	Get advanced statistics	Same as `nba_get_stats`
`nba_get_box_scores`	Get box scores	`dates`, `seasons`, `team_ids`, `game_ids`, `postseason`, pagination
`nba_get_live_box_scores`	Get live box scores	Same as `nba_get_box_scores`
`nba_get_standings`	Get team standings	`season`, `conference`, `division`
`nba_get_leaders`	Get statistical leaders	`season`, `stat_type`, `per_page`
`nba_get_player_injuries`	Get player injuries	`player_ids`, `team_ids`, pagination
`nba_get_betting_odds`	Get betting odds for games	`dates`, `game_ids`, pagination
`nba_get_lineups`	Get game lineups	`game_ids` (required), pagination
`nba_get_player_props`	Get player prop betting odds	`game_id` (required), `player_id`, `prop_type`
`nba_get_contracts_by_team`	Get player contracts by team	`team_id` (required), `season`
`nba_get_contracts_by_player`	Get player contracts	`player_id` (required), `seasons`, pagination
`nba_get_contracts_aggregate`	Get aggregated contract data	`player_id` (required)
`nba_get_plays`	Get play-by-play data	`game_id` (required)

NFL (17 tools)

Tool	Description	Parameters
`nfl_get_teams`	Get all NFL teams	`division`, `conference`
`nfl_get_team_by_id`	Get specific NFL team	`id` (required)
`nfl_get_players`	Get NFL players	`search`, `first_name`, `last_name`, `team_ids`, `player_ids`, `position`, pagination
`nfl_get_player_by_id`	Get specific NFL player	`id` (required)
`nfl_get_active_players`	Get active NFL players	Same as `nfl_get_players`
`nfl_get_games`	Get NFL games	`dates`, `seasons`, `team_ids`, `weeks`, `postseason`, `start_date`, `end_date`, pagination
`nfl_get_game_by_id`	Get specific NFL game	`id` (required)
`nfl_get_stats`	Get NFL statistics	`dates`, `seasons`, `team_ids`, `player_ids`, `game_ids`, `weeks`, `postseason`, pagination
`nfl_get_season_stats`	Get season statistics	`season`, `player_ids`, `team_ids`, `postseason`, pagination
`nfl_get_standings`	Get team standings	`season`, `conference`, `division`
`nfl_get_player_injuries`	Get player injuries	`player_ids`, `team_ids`, pagination
`nfl_get_advanced_rushing_stats`	Get advanced rushing stats	`season`, `week`, `player_ids`, `team_ids`, `position`, pagination
`nfl_get_advanced_passing_stats`	Get advanced passing stats	Same as rushing
`nfl_get_advanced_receiving_stats`	Get advanced receiving stats	Same as rushing
`nfl_get_betting_odds`	Get betting odds for games	`season`, `week`, `game_ids`, pagination
`nfl_get_team_roster`	Get team roster/depth chart	`id` (required), `season`
`nfl_get_player_props`	Get player prop betting odds	`game_id` (required), `player_id`, `prop_type`, `vendors`

MLB (14 tools)

Tool	Description	Parameters
`mlb_get_teams`	Get all MLB teams	`division`, `league`
`mlb_get_team_by_id`	Get specific MLB team	`id` (required)
`mlb_get_players`	Get MLB players	`search`, `first_name`, `last_name`, `team_ids`, `player_ids`, `position`, `active`, pagination
`mlb_get_player_by_id`	Get specific MLB player	`id` (required)
`mlb_get_active_players`	Get active MLB players	Same as `mlb_get_players`
`mlb_get_games`	Get MLB games	`dates`, `seasons`, `team_ids`, `postseason`, `start_date`, `end_date`, pagination
`mlb_get_game_by_id`	Get specific MLB game	`id` (required)
`mlb_get_stats`	Get MLB statistics	`dates`, `seasons`, `team_ids`, `player_ids`, `game_ids`, `postseason`, pagination
`mlb_get_season_stats`	Get season statistics	`season`, `player_ids`, `team_ids`, `postseason`, pagination
`mlb_get_team_season_stats`	Get team season stats	`season`, `team_ids`, `postseason`, pagination
`mlb_get_standings`	Get team standings	`season`, `league`, `division`
`mlb_get_player_injuries`	Get player injuries	`player_ids`, `team_ids`, pagination
`mlb_get_player_splits`	Get player splits by category	`player_id` (required), `season` (required)
`mlb_get_player_versus`	Get player vs player matchups	`player_id` (required), `opponent_team_id` (required)

EPL (17 tools)

Tool	Description	Parameters
`epl_get_teams`	Get all EPL teams	pagination
`epl_get_team_by_id`	Get specific EPL team	`id` (required)
`epl_get_team_players`	Get team players	`id` (required), pagination
`epl_get_team_season_stats`	Get team season stats	`id` (required), `season`, `stat_types`
`epl_get_team_stats_leaders`	Get team stat leaders	`season`, `stat_type`, `per_page`
`epl_get_standings`	Get EPL standings	`season`
`epl_get_players`	Get EPL players	`search`, `team_ids`, `player_ids`, `position`, pagination
`epl_get_player_by_id`	Get specific EPL player	`id` (required)
`epl_get_player_season_stats`	Get player season stats	`id` (required), `season`, `stat_types`
`epl_get_player_stats_leaders`	Get player stat leaders	`season`, `stat_type`, `per_page`
`epl_get_games`	Get EPL games	`dates`, `seasons`, `team_ids`, `weeks`, `start_date`, `end_date`, pagination
`epl_get_game_by_id`	Get specific EPL game	`id` (required)
`epl_get_game_lineups`	Get game lineups	`id` (required)
`epl_get_game_goals`	Get game goals	`id` (required)
`epl_get_game_team_stats`	Get game team stats	`id` (required)
`epl_get_game_player_stats`	Get game player stats	`id` (required)
`epl_get_betting_odds`	Get betting odds for games	`season`, `week`, `game_ids`, pagination
`epl_get_player_props`	Get player prop betting odds	`game_id` (required), `player_id`, `prop_type`

NHL (16 tools)

Tool	Description	Parameters
`nhl_get_teams`	Get all NHL teams	`conference`, `division`, pagination
`nhl_get_team_by_id`	Get specific NHL team	`id` (required)
`nhl_get_team_season_stats`	Get team season stats	`id` (required), `season`
`nhl_get_team_stats_leaders`	Get team stat leaders	`season`, `stat_type`, `per_page`
`nhl_get_players`	Get NHL players	`search`, `team_ids`, `player_ids`, `position`, pagination
`nhl_get_player_by_id`	Get specific NHL player	`id` (required)
`nhl_get_player_season_stats`	Get player season stats	`id` (required), `season`
`nhl_get_player_stats_leaders`	Get player stat leaders	`season`, `stat_type`, `per_page`
`nhl_get_games`	Get NHL games	`dates`, `seasons`, `team_ids`, `season_type`, `start_date`, `end_date`, pagination
`nhl_get_game_by_id`	Get specific NHL game	`id` (required)
`nhl_get_standings`	Get NHL standings	`season`, `conference`, `division`
`nhl_get_box_scores`	Get NHL box scores	`dates`, `seasons`, `team_ids`, `game_ids`, `season_type`, pagination
`nhl_get_betting_odds`	Get betting odds for games	`dates`, `game_ids`, pagination
`nhl_get_player_props`	Get player prop betting odds	`game_id` (required), `player_id`, `prop_type`
`nhl_get_plays`	Get play-by-play data	`game_id` (required)
`nhl_get_player_injuries`	Get currently injured NHL players	-

WNBA (20 tools)

Tool	Description	Parameters
`wnba_get_teams`	Get all WNBA teams	`conference`
`wnba_get_team_by_id`	Get specific WNBA team	`id` (required)
`wnba_get_players`	Get WNBA players	`search`, `first_name`, `last_name`, `team_ids`, `player_ids`, pagination
`wnba_get_player_by_id`	Get specific WNBA player	`id` (required)
`wnba_get_active_players`	Get active WNBA players	Same as `wnba_get_players`
`wnba_get_games`	Get WNBA games	`dates`, `seasons`, `team_ids`, `season_type`, `start_date`, `end_date`, pagination
`wnba_get_game_by_id`	Get specific WNBA game	`id` (required)
`wnba_get_player_stats`	Get player game statistics	`game_ids`, `dates`, `seasons`, `player_ids`, `team_ids`, pagination
`wnba_get_team_stats`	Get team game statistics	`game_ids`, `dates`, `seasons`, `team_ids`, pagination
`wnba_get_player_season_stats`	Get player season stats	`player_ids`, `team_ids`, `season`, `season_type`, pagination
`wnba_get_team_season_stats`	Get team season stats	`team_ids`, `season`, `season_type`, pagination
`wnba_get_player_game_advanced_stats`	Get player game advanced stats	`game_ids`, `dates`, `season`, `seasons`, `player_ids`, `team_ids`, `season_type`, `postseason`, pagination
`wnba_get_team_game_advanced_stats`	Get team game advanced stats	`game_ids`, `dates`, `season`, `seasons`, `team_ids`, `season_type`, `postseason`, pagination
`wnba_get_player_season_advanced_stats`	Get player season advanced stats	`season` (required), `player_ids`, `team_ids`, `season_type`, `postseason`, `scope`, `measure_type`, `per_mode`, pagination
`wnba_get_team_season_advanced_stats`	Get team season advanced stats	`season` (required), `team_ids`, `season_type`, `postseason`, `scope`, `measure_type`, `per_mode`, pagination
`wnba_get_player_shot_locations`	Get player shot locations	`season` (required), `player_ids`, `team_ids`, `season_type`, `postseason`, `distance_range`, `per_mode`, pagination
`wnba_get_team_shot_locations`	Get team shot locations	`season` (required), `team_ids`, `season_type`, `postseason`, `measure_type`, `distance_range`, `per_mode`, pagination
`wnba_get_standings`	Get WNBA standings	`season`, `conference`
`wnba_get_player_injuries`	Get player injuries	`player_ids`, `team_ids`, pagination
`wnba_get_plays`	Get play-by-play data	`game_id` (required)

NCAAF (17 tools)

Tool	Description	Parameters
`ncaaf_get_conferences`	Get all NCAAF conferences	-
`ncaaf_get_conference_by_id`	Get specific NCAAF conference	`id` (required)
`ncaaf_get_teams`	Get all NCAAF teams	`conference`, pagination
`ncaaf_get_team_by_id`	Get specific NCAAF team	`id` (required)
`ncaaf_get_players`	Get NCAAF players	`search`, `first_name`, `last_name`, `team_ids`, `player_ids`, `position`, pagination
`ncaaf_get_active_players`	Get active NCAAF players	Same as `ncaaf_get_players`
`ncaaf_get_player_by_id`	Get specific NCAAF player	`id` (required)
`ncaaf_get_standings`	Get NCAAF standings	`season`, `conference_id`, pagination
`ncaaf_get_games`	Get NCAAF games	`dates`, `seasons`, `team_ids`, `weeks`, `start_date`, `end_date`, pagination
`ncaaf_get_game_by_id`	Get specific NCAAF game	`id` (required)
`ncaaf_get_rankings`	Get NCAAF rankings	`season`, `week`, pagination
`ncaaf_get_plays`	Get play-by-play data	`game_id` (required)
`ncaaf_get_player_stats`	Get player game statistics	`game_ids`, `dates`, `seasons`, `player_ids`, `team_ids`, `weeks`, pagination
`ncaaf_get_team_stats`	Get team game statistics	`game_ids`, `dates`, `seasons`, `team_ids`, `weeks`, pagination
`ncaaf_get_player_season_stats`	Get player season stats	`season` (required), `player_ids`, `team_ids`, pagination
`ncaaf_get_team_season_stats`	Get team season stats	`season` (required), `team_ids`, pagination
`ncaaf_get_betting_odds`	Get betting odds for games	`season`, `week`, `game_ids`, pagination

NCAAB (18 tools)

Tool	Description	Parameters
`ncaab_get_conferences`	Get all NCAAB conferences	-
`ncaab_get_conference_by_id`	Get specific NCAAB conference	`id` (required)
`ncaab_get_teams`	Get all NCAAB teams	`conference`, pagination
`ncaab_get_team_by_id`	Get specific NCAAB team	`id` (required)
`ncaab_get_players`	Get NCAAB players	`search`, `first_name`, `last_name`, `team_ids`, `player_ids`, `position`, pagination
`ncaab_get_player_by_id`	Get specific NCAAB player	`id` (required)
`ncaab_get_active_players`	Get active NCAAB players	Same as `ncaab_get_players`
`ncaab_get_standings`	Get NCAAB standings	`season`, `conference_id`, pagination
`ncaab_get_games`	Get NCAAB games	`dates`, `seasons`, `team_ids`, `weeks`, `start_date`, `end_date`, pagination
`ncaab_get_game_by_id`	Get specific NCAAB game	`id` (required)
`ncaab_get_rankings`	Get NCAAB rankings	`season`, `week`, pagination
`ncaab_get_plays`	Get play-by-play data	`game_id` (required)
`ncaab_get_player_stats`	Get player game statistics	`game_ids`, `dates`, `seasons`, `player_ids`, `team_ids`, `weeks`, pagination
`ncaab_get_team_stats`	Get team game statistics	`game_ids`, `dates`, `seasons`, `team_ids`, `weeks`, pagination
`ncaab_get_player_season_stats`	Get player season stats	`season` (required), `player_ids`, `team_ids`, pagination
`ncaab_get_team_season_stats`	Get team season stats	`season` (required), `team_ids`, pagination
`ncaab_get_brackets`	Get tournament brackets	`season`, pagination
`ncaab_get_betting_odds`	Get betting odds for games	`dates`, `game_ids`, pagination

MMA (12 tools)

Tool	Description	Parameters
`mma_get_leagues`	Get all MMA leagues (UFC, etc.)	-
`mma_get_league_by_id`	Get specific MMA league	`id` (required)
`mma_get_events`	Get MMA events	`date`, `year`, pagination
`mma_get_event_by_id`	Get specific MMA event	`id` (required)
`mma_get_fighters`	Get MMA fighters	`search`, `fighter_ids`, pagination
`mma_get_fighter_by_id`	Get specific MMA fighter	`id` (required)
`mma_get_fights`	Get MMA fights	`fight_ids`, `fighter_ids`, `event_ids`, pagination
`mma_get_fight_by_id`	Get specific MMA fight	`id` (required)
`mma_get_rankings`	Get MMA fighter rankings	-
`mma_get_fight_stats`	Get detailed fight statistics	`fight_ids`, `fighter_ids`, `event_ids`, pagination
`mma_get_fight_stat_by_id`	Get specific fight statistics	`id` (required)
`mma_get_betting_odds`	Get MMA betting odds	`event_id`, `fight_id`

CS2 (16 tools)

Tool	Description	Parameters
`cs2_get_teams`	Get all CS2 teams	`search`, pagination
`cs2_get_team_by_id`	Get specific CS2 team	`id` (required)
`cs2_get_players`	Get CS2 players	`search`, `team_id`, `active`, pagination
`cs2_get_player_by_id`	Get specific CS2 player	`id` (required)
`cs2_get_tournaments`	Get all CS2 tournaments	`search`, pagination
`cs2_get_tournament_by_id`	Get specific CS2 tournament	`id` (required)
`cs2_get_tournament_teams`	Get teams in a tournament	`tournament_id` (required)
`cs2_get_team_map_pool`	Get team map pool stats (ALL-STAR tier)	`team_id` (required)
`cs2_get_rankings`	Get CS2 team rankings (ALL-STAR tier)	-
`cs2_get_matches`	Get CS2 matches (GOAT tier)	`team_ids`, `tournament_ids`, `dates`, pagination
`cs2_get_match_by_id`	Get specific CS2 match (GOAT tier)	`id` (required)
`cs2_get_match_maps`	Get maps for matches (GOAT tier)	`match_ids` (required)
`cs2_get_match_map_stats`	Get round-by-round map stats (GOAT tier)	`match_map_id` (required)
`cs2_get_player_match_stats`	Get player stats for match (GOAT tier)	`match_id` (required)
`cs2_get_player_match_map_stats`	Get player stats for specific map (GOAT tier)	`match_map_id` (required)
`cs2_get_player_accuracy_stats`	Get player accuracy by body part (GOAT tier)	`player_id` (required)

League of Legends (16 tools)

Tool	Description	Parameters
`lol_get_teams`	Get all professional LOL teams	`search`, pagination
`lol_get_players`	Get LOL players	`search`, `team_id`, pagination
`lol_get_champions`	Get all LOL champions	-
`lol_get_items`	Get all LOL in-game items	-
`lol_get_spells`	Get all LOL summoner spells	-
`lol_get_rune_paths`	Get LOL rune paths	-
`lol_get_runes`	Get all LOL runes	-
`lol_get_tournaments`	Get LOL tournaments (ALL-STAR tier)	pagination
`lol_get_tournament_teams`	Get teams in a tournament (ALL-STAR tier)	`tournament_id` (required)
`lol_get_tournament_roster`	Get tournament roster (ALL-STAR tier)	`tournament_id` (required), `team_id` (required)
`lol_get_champion_stats`	Get champion aggregate stats (ALL-STAR tier)	-
`lol_get_matches`	Get LOL matches (GOAT tier)	`tournament_id`, `team_id`, pagination
`lol_get_match_maps`	Get games within a match (GOAT tier)	`match_id` (required)
`lol_get_player_match_map_stats`	Get player stats for games (GOAT tier)	`match_map_id`, `player_id`, pagination
`lol_get_team_match_map_stats`	Get team stats for games (GOAT tier)	`match_map_id`, `team_id`, pagination
`lol_get_player_overall_stats`	Get player career stats (GOAT tier)	`player_id`, pagination

Dota 2 (14 tools)

Tool	Description	Parameters
`dota_get_teams`	Get all professional Dota 2 teams	`search`, pagination
`dota_get_players`	Get Dota 2 players	`search`, `team_id`, pagination
`dota_get_heroes`	Get all Dota 2 heroes	-
`dota_get_items`	Get all Dota 2 in-game items	-
`dota_get_abilities`	Get all Dota 2 hero abilities	-
`dota_get_tournaments`	Get Dota 2 tournaments (ALL-STAR tier)	pagination
`dota_get_tournament_teams`	Get teams in a tournament (ALL-STAR tier)	`tournament_id` (required)
`dota_get_tournament_roster`	Get tournament roster (ALL-STAR tier)	`tournament_id` (required), `team_id` (required)
`dota_get_hero_stats`	Get hero aggregate stats (ALL-STAR tier)	-
`dota_get_matches`	Get Dota 2 matches (GOAT tier)	`tournament_id`, `team_id`, pagination
`dota_get_match_maps`	Get games within a match (GOAT tier)	`match_id` (required)
`dota_get_player_match_map_stats`	Get player stats for games (GOAT tier)	`match_map_id`, `player_id`, pagination
`dota_get_team_match_map_stats`	Get team stats for games (GOAT tier)	`match_map_id`, `team_id`, pagination
`dota_get_player_overall_stats`	Get player career stats (GOAT tier)	`player_id`, pagination

FIFA World Cup 2026 (6 tools)

Tool	Description	Parameters
`fifa_get_teams`	Get all FIFA World Cup 2026 participating nations	-
`fifa_get_stadiums`	Get all FIFA World Cup 2026 host stadiums	-
`fifa_get_group_standings`	Get group stage standings (Requires ALL-STAR tier)	-
`fifa_get_matches`	Get all matches including group and knockout (GOAT tier)	-
`fifa_get_betting_odds`	Get betting odds for matches (Requires GOAT tier)	-
`fifa_get_futures_odds`	Get futures betting odds (e.g., tournament winner, GOAT)	-

La Liga (11 tools)

Tool	Description	Parameters
`laliga_get_teams`	Get all La Liga teams	`season` (required)
`laliga_get_rosters`	Get team rosters	`team_id` (required), `season`, pagination
`laliga_get_players`	Get La Liga players	`season` (required), `team_ids`, `search`, pagination
`laliga_get_standings`	Get La Liga standings	`season` (required)
`laliga_get_matches`	Get La Liga matches	`season`, `team_ids`, `dates`, `start_date`, `end_date`, pagination
`laliga_get_match_events`	Get match events (goals, cards, etc.)	`match_ids`, pagination
`laliga_get_match_lineups`	Get match lineups	`match_ids`, pagination
`laliga_get_player_match_stats`	Get player match statistics	`match_ids`, `player_ids`, pagination
`laliga_get_team_match_stats`	Get team match statistics	`match_ids`, `team_ids`, pagination
`laliga_get_betting_odds`	Get betting odds for matches	`match_ids`, `dates`, pagination
`laliga_get_player_props`	Get player prop betting odds	`match_id` (required), `player_id`, `prop_type`

Serie A (11 tools)

Tool	Description	Parameters
`seriea_get_teams`	Get all Serie A teams	`season` (required)
`seriea_get_rosters`	Get team rosters	`team_id` (required), `season`, pagination
`seriea_get_players`	Get Serie A players	`season` (required), `team_ids`, `search`, pagination
`seriea_get_standings`	Get Serie A standings	`season` (required)
`seriea_get_matches`	Get Serie A matches	`season`, `team_ids`, `dates`, `start_date`, `end_date`, pagination
`seriea_get_match_events`	Get match events (goals, cards, etc.)	`match_ids`, pagination
`seriea_get_match_lineups`	Get match lineups	`match_ids`, pagination
`seriea_get_player_match_stats`	Get player match statistics	`match_ids`, `player_ids`, pagination
`seriea_get_team_match_stats`	Get team match statistics	`match_ids`, `team_ids`, pagination
`seriea_get_betting_odds`	Get betting odds for matches	`match_ids`, `dates`, pagination
`seriea_get_player_props`	Get player prop betting odds	`match_id` (required), `player_id`, `prop_type`

UEFA Champions League (12 tools)

Tool	Description	Parameters
`ucl_get_teams`	Get all UCL teams	`season` (required)
`ucl_get_rosters`	Get team rosters	`team_id` (required), `season`, pagination
`ucl_get_players`	Get UCL players	`season` (required), `team_ids`, `search`, pagination
`ucl_get_standings`	Get UCL standings	`season` (required)
`ucl_get_matches`	Get UCL matches	`season`, `team_ids`, `dates`, `start_date`, `end_date`, pagination
`ucl_get_match_events`	Get match events (goals, cards, etc.)	`match_ids`, pagination
`ucl_get_match_lineups`	Get match lineups	`match_ids`, pagination
`ucl_get_player_match_stats`	Get player match statistics	`match_ids`, `player_ids`, pagination
`ucl_get_team_match_stats`	Get team match statistics	`match_ids`, `team_ids`, pagination
`ucl_get_betting_odds`	Get betting odds for matches	`match_ids`, `dates`, pagination
`ucl_get_player_props`	Get player prop betting odds	`match_id` (required), `player_id`, `prop_type`
`ucl_get_futures_odds`	Get futures betting odds	-

Bundesliga (11 tools)

Tool	Description	Parameters
`bundesliga_get_teams`	Get all Bundesliga teams	`season` (required)
`bundesliga_get_rosters`	Get team rosters	`team_id` (required), `season`, pagination
`bundesliga_get_players`	Get Bundesliga players	`season` (required), `team_ids`, `search`, pagination
`bundesliga_get_standings`	Get Bundesliga standings	`season` (required)
`bundesliga_get_matches`	Get Bundesliga matches	`season`, `team_ids`, `dates`, `start_date`, `end_date`, pagination
`bundesliga_get_match_events`	Get match events (goals, cards, etc.)	`match_ids`, pagination
`bundesliga_get_match_lineups`	Get match lineups	`match_ids`, pagination
`bundesliga_get_player_match_stats`	Get player match statistics	`match_ids`, `player_ids`, pagination
`bundesliga_get_team_match_stats`	Get team match statistics	`match_ids`, `team_ids`, pagination
`bundesliga_get_betting_odds`	Get betting odds for matches	`match_ids`, `dates`, pagination
`bundesliga_get_player_props`	Get player prop betting odds	`match_id` (required), `player_id`, `prop_type`

Ligue 1 (11 tools)

Tool	Description	Parameters
`ligue1_get_teams`	Get all Ligue 1 teams	`season` (required)
`ligue1_get_rosters`	Get team rosters	`team_id` (required), `season`, pagination
`ligue1_get_players`	Get Ligue 1 players	`season` (required), `team_ids`, `search`, pagination
`ligue1_get_standings`	Get Ligue 1 standings	`season` (required)
`ligue1_get_matches`	Get Ligue 1 matches	`season`, `team_ids`, `dates`, `start_date`, `end_date`, pagination
`ligue1_get_match_events`	Get match events (goals, cards, etc.)	`match_ids`, pagination
`ligue1_get_match_lineups`	Get match lineups	`match_ids`, pagination
`ligue1_get_player_match_stats`	Get player match statistics	`match_ids`, `player_ids`, pagination
`ligue1_get_team_match_stats`	Get team match statistics	`match_ids`, `team_ids`, pagination
`ligue1_get_betting_odds`	Get betting odds for matches	`match_ids`, `dates`, pagination
`ligue1_get_player_props`	Get player prop betting odds	`match_id` (required), `player_id`, `prop_type`

Authentication

The server forwards Authorization headers to the BALLDONTLIE API. Your MCP client should include the API key in requests:

code

Authorization: YOUR_API_KEY

Error Handling

The server provides detailed error information:

Authentication Errors (401): Missing or invalid API key
Authorization Errors (403): Insufficient tier access
Validation Errors (400): Invalid parameters
Rate Limiting (429): Request rate exceeded
Server Errors (5xx): Backend API issues

Development

bash

# Clone and install
git clone <repository>
cd mcp-server
npm install

# Build
npm run build

# Run in development
npm run dev

# Clean build
npm run clean

API Tiers

BALLDONTLIE offers different tiers with varying access levels:

Free: Basic endpoints (teams, players, games)
ALL-STAR ($9.99/mo): Includes stats, injuries, standings
GOAT ($39.99/mo): Full access including advanced stats, box scores, betting odds

Support

License

MIT

Install

claude_desktop_config.json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.balldontlie.io/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.