# Balldontlie [Health: Active]

**Category:** 🏃 Sports  
**Repository:** https://github.com/pipeworx-io/mcp-balldontlie  
**GitHub Stars:** 0  
**npm Downloads (last month):** 434  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/balldontlie

## Description
balldontlie.io NBA stats (free API key required)

## Tools
Capabilities this server exposes over MCP:

- **teams** — All 30 NBA teams: ID, name, city, abbreviation, conference, division. Use as a directory to resolve a team name into the numeric team_id required by other balldontlie tools.
- **team** — Single NBA team by ID: name, abbreviation, city, conference, division. Use after teams() to confirm details.
- **players** — NBA player roster — search by name substring or filter by team. Returns ID, first/last name, position, height, weight, jersey number, and team. Use to resolve a player name to a numeric player_id required by stats/season_averages.
- **player** — Single NBA player by ID: name, position, height, weight, jersey, team. Use after players() to confirm.
- **games** — NBA games filtered by season, team, or date range. Returns matchup, scores, date, season, postseason flag, status. Use for "did the Lakers win last night", schedule lookup, historical game search.
- **game** — Single NBA game by ID: matchup, scores, date, period, time, venue, season, postseason flag. Use after games() to fetch detail.
- **season_averages** — Fetch per-season NBA stat averages for one or more player_ids in a given season year; returns PTS, REB, AST, FG%, and other averages per player.
- **stats** — Per-game NBA player box-score stats filtered by player, team, game, or season. Returns PTS, REB, AST, STL, BLK, TO, FG%, FT%, 3P%, minutes, +/-. Use for individual game performance lookup, box-score analysis, fantasy stats.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `PLATFORM_BALLDONTLIE_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

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

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

For local stdio use:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/balldontlie/readme_