Skip to content
MCP server

Balldontlie

NBA teams, players, games and box-score stats via the balldontlie API, as MCP tools

Install
Pricing
Freemium
Platforms
API, CLI, self-hosted
Runs
Locally or Remotely
Version
0.2.1
Listing updated
today

Similar MCP servers

About Balldontlie

Balldontlie is a freemium MCP server for sports data. It can run locally on your machine or as a hosted remote server.

The README describes this as an unofficial MCP wrapper around the balldontlie.io NBA API, exposed through the Pipeworx gateway. It gives an AI client eight tools covering the 30 NBA teams, player rosters and profiles, games with scores and schedules, per-season player averages, and per-game box-score stats.

The usual workflow is to resolve a team or player name into a numeric ID with the directory tools first, then pass that ID into the game and stats lookups. Results are returned as structured fields such as points, rebounds, assists, shooting percentages and minutes.

It suits developers and analysts who want an assistant to answer questions about NBA results or player performance without writing their own API client. Access uses a balldontlie key that you supply, and anonymous calls are capped per day.

Install

Run in a terminal

claude mcp add --transport http balldontlie https://gateway.pipeworx.io/balldontlie/mcp

Add to Settings → Connectors → Add custom connector

https://gateway.pipeworx.io/balldontlie/mcp
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "balldontlie": {
      "url": "https://gateway.pipeworx.io/balldontlie/mcp"
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "balldontlie": {
      "type": "http",
      "url": "https://gateway.pipeworx.io/balldontlie/mcp"
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Using several servers? Build one config file with the MCP config generator.

Configuration

  • PIPEWORX_API_KEYOptional Pipeworx API key. Without it calls are anonymous and capped daily; a free key raises the cap.

Tools this server provides (8)

Taken from the project documentation; the running server may differ.

teams
All 30 NBA teams with ID, name, city, abbreviation, conference and division.
team
Single NBA team by ID with name, abbreviation, city, conference and division.
players
NBA player roster, searchable by name substring or filterable by team.
player
Single NBA player by ID with name, position, height, weight, jersey and team.
games
NBA games filtered by season, team or date range with matchup, scores and status.
game
Single NBA game by ID with matchup, scores, date, period, time, venue and season.
season_averages
Per-season stat averages for one or more player IDs in a given season.
stats
Per-game player box-score stats filtered by player, team, game or season.

What it does

Team directory lookup
Lists all 30 NBA teams with conference and division, returning the numeric team IDs that other tools need.
Player search and profiles
Searches the roster by name or team and returns position, height, weight, jersey number and team for a given player.
Game schedules and results
Filters games by season, team or date range and returns matchups, scores, status and postseason flag.
Season averages
Returns per-season averages such as points, rebounds, assists and shooting percentages for one or more players.
Box-score stats
Provides per-game player stats including minutes, steals, blocks, turnovers and plus/minus, filterable by player, team, game or season.
Bring-your-own key
Accepts a balldontlie API key per connection, with anonymous use capped at a daily limit.

Good for

  • Answering questions about whether a team won a recent game
  • Looking up a player's season averages for a fantasy or analytics model
  • Building a schedule view for a given NBA team and date range
  • Pulling box-score lines for a specific game to compare player performance

Pricing

Freemium

Free anonymous and free account tiers on the Pipeworx gateway; paid credits and subscriptions for higher usage. The upstream balldontlie key is supplied by the user.

Prices change. Check pipeworx.io before you buy.

Balldontlie FAQ

Is this an official balldontlie product?

No. The README states it is an independent, unofficial integration that is not affiliated with or endorsed by the upstream provider.

Do I need an API key?

A balldontlie key is required for the upstream API. Without a Pipeworx key, calls are anonymous and capped at 50 per day; a free Pipeworx account raises the cap to 200 per day.

Which tools does the endpoint expose?

The pack provides eight NBA tools: teams, team, players, player, games, game, season_averages and stats. The endpoint also lists shared Pipeworx gateway tools such as ask_pipeworx.

Is the server open source?

The README is published under the MIT licence in the repository and is distributed on npm as @pipeworx/mcp-balldontlie, though the npm package forwards calls to the hosted gateway.

Is Balldontlie free?

Balldontlie has a free plan, with paid plans for more usage or features.

How do I add Balldontlie to Claude Code?

Run this command in your terminal: claude mcp add --transport http balldontlie https://gateway.pipeworx.io/balldontlie/mcp

What are the best alternatives to Balldontlie?

The closest alternatives to Balldontlie are LeagueApps MCP by usefulapi, The Blue Alliance, Sports Events Results MCP, Realtime Sports API and LiveScore MCP.

Where this comes from

  • Description: written from the project's README, the project's website and its MCP Registry entry.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers