Balldontlie

liveSports

balldontlie.io NBA API — query NBA teams, players, games, stats, and season averages.

8tools
0msauth
free tier50 calls/day
🔑Authentication

BYO key only — free key at app.balldontlie.io. Pass _apiKey on the gateway URL.

Config with credentials
{
  "mcpServers": {
    "pipeworx-balldontlie": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gateway.pipeworx.io/balldontlie/mcp?_apiKey=your_balldontlie_key"
      ]
    }
  }
}

Get an API key →

Tools

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.

No parameters required.

▶Try it
team

Single NBA team by ID: name, abbreviation, city, conference, division. Use after teams() to confirm details.

No parameters required.

▶Try it
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 requ

No parameters required.

▶Try it
player

Single NBA player by ID: name, position, height, weight, jersey, team. Use after players() to confirm.

No parameters required.

▶Try it
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.

No parameters required.

▶Try it
game

Single NBA game by ID: matchup, scores, date, period, time, venue, season, postseason flag. Use after games() to fetch detail.

No parameters required.

▶Try it
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.

No parameters required.

▶Try it
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 a

No parameters required.

▶Try it

Test with curl

The gateway speaks JSON-RPC 2.0 over HTTP POST. You can test any pack directly from the terminal.

List available tools
bash
curl -X POST https://gateway.pipeworx.io/balldontlie/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Call a tool
bash
curl -X POST https://gateway.pipeworx.io/balldontlie/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"teams","arguments":{}}}'

Use with the SDK

Install @pipeworx/sdk to call tools from any TypeScript/Node project.

TypeScript
import { Pipeworx } from '@pipeworx/sdk';
const px = new Pipeworx();
const result = await px.call("teams", {});
ask_pipeworx
// Or ask in plain English:
const answer = await px.ask("balldontlie");