Balldontlie Api Mcp

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

npm install @balldontlie/mcp-server

Quick Start

1. Get API Key

Sign up at BALLDONTLIE to get your free 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:

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

Replace `` with your actual API key from BALLDONTLIE.

Option B: Run from Source

Clone and run from source code:

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:

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

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 DDAGENTHOST) | | 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 stat

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: balldontlie-api
• Source: balldontlie-api/mcp
• License: MIT

Install and usage instructions live in the source repository linked above.