BALLDONTLIE

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., Claude Desktop) to use the hosted server:

{
  "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:

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": "<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

---

README truncated. View full README on GitHub.