
Balldontlie
NBA teams, players, games and box-score stats via the balldontlie API, as MCP tools
- 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/mcpAdd to Settings → Connectors → Add custom connector
https://gateway.pipeworx.io/balldontlie/mcpAdd to ~/.cursor/mcp.json
{
"mcpServers": {
"balldontlie": {
"url": "https://gateway.pipeworx.io/balldontlie/mcp"
}
}
}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.