Balldontlie

What Balldontlie does

Balldontlie exposes NBA data from the balldontlie.io API as MCP tools. The coverage includes all 30 teams, player records and rosters, game schedules and results, per-season player averages, and individual game or filtered box-score statistics.

The lookup tools are designed to work together. Use teams to find a numeric team ID, then pass that ID to team, games, or player-related filters. Similarly, players resolves a name or team roster to a numeric player ID for player, stats, and season_averages. Detail tools return fields such as names, teams, scores, dates, positions, shooting percentages, minutes, and plus/minus values depending on the resource.

How it works

The hosted MCP endpoint is https://gateway.pipeworx.io/balldontlie/mcp. It lists the Balldontlie tools along with shared Pipeworx tools such as ask_pipeworx, discover_tools, search_within, and memory-related tools. ask_pipeworx can route a natural-language question to the appropriate catalog tool. A full Pipeworx gateway connection is also available at https://gateway.pipeworx.io/mcp.

For a pack-only connection, run the package locally with npx -y @pipeworx/mcp-balldontlie. The local process communicates over stdin and stdout and exposes only the Balldontlie tools, without the gateway's shared meta-tools or cross-catalog routing.

Setup and configuration

Add the hosted endpoint to an MCP client as follows:

{
  "mcpServers": {
    "balldontlie": {
      "url": "https://gateway.pipeworx.io/balldontlie/mcp"
    }
  }
}

For local stdio use:

{
  "mcpServers": {
    "balldontlie": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-balldontlie"]
    }
  }
}

Authentication requires a balldontlie.io API key. Gateway authentication can use the PLATFORM_BALLDONTLIE_KEY platform key, while requests can also provide a key with the _apiKey parameter. The free API tier permits five requests per minute.

Tools and capabilities

• teams() lists every NBA team with its ID, name, city, abbreviation, conference, and division.
• team(id) retrieves one team's identifying and conference details.
• players(query?, team_ids?, cursor?, per_page?) searches players by name or team and returns roster information.
• player(id) retrieves one player's profile, including position, physical details, jersey number, and team.
• games(seasons?, team_ids?, dates?, postseason?, cursor?, per_page?) searches games by season, team, date, or postseason status.
• game(id) returns detailed information for one game, including matchup, scores, venue, period, and time.
• season_averages(season, player_ids) returns per-season averages for selected players.
• stats(seasons?, player_ids?, game_ids?, postseason?, cursor?, per_page?) filters player box-score statistics by season, player, game, or postseason status.

These operations support schedule checks, historical game searches, roster lookups, player-stat comparisons, and fantasy or box-score analysis.