Skip to main content
Glama
nba-mcp

nba-mcp

by ufo2243

nba-mcp

Node.js / TypeScript MCP server for NBA live data and stats from NBA.com.

This server exposes a focused set of read-only Model Context Protocol tools over stdio. It uses NBA.com's public website endpoints:

  • Live data: https://cdn.nba.com/static/json/liveData/...

  • Stats data: https://stats.nba.com/stats/{endpoint}

NBA.com does not treat these as a formally supported public developer API, so endpoints, required parameters, headers, rate limits, and network access can change without notice.

Install

npm install -g nba-mcp

Related MCP server: SportRadar MCP Server

Run

Use the published npm package directly from MCP clients:

{
  "mcpServers": {
    "nba": {
      "command": "npx",
      "args": ["-y", "nba-mcp"]
    }
  }
}

Or run the installed binary:

nba-mcp

For local development from a checkout:

npm install
npm run build
npm start

Local MCP clients can also use the built stdio entrypoint:

{
  "mcpServers": {
    "nba": {
      "command": "node",
      "args": ["/absolute/path/to/nba-mcp/dist/index.js"]
    }
  }
}

During development:

npm run dev

Tools

  • nba_stats_endpoint - advanced raw caller for documented stats.nba.com endpoints

  • nba_search_teams - local static NBA team lookup

  • nba_live_scoreboard - today's live scoreboard

  • nba_live_boxscore - live box score by gameId

  • nba_live_play_by_play - live play-by-play by gameId

  • nba_live_odds - today's live odds when available

  • nba_schedule_by_date - schedule and scores for a date

  • nba_search_players - player search via playerindex

  • nba_player_info - player bio and headline stats

  • nba_player_career_stats - player career and season totals

  • nba_player_game_log - player game log for a season

  • nba_team_game_log - team game log for a season

  • nba_league_standings - standings by season

  • nba_league_player_stats - league-wide player dashboard stats

  • nba_league_team_stats - league-wide team dashboard stats

Environment

NBA_STATS_BASE_URL=https://stats.nba.com/stats
NBA_LIVE_BASE_URL=https://cdn.nba.com/static/json/liveData
NBA_STATS_TIMEOUT_MS=30000
NBA_LIVE_TIMEOUT_MS=10000
NBA_MAX_RETRIES=2
NBA_STATS_RATE_LIMIT_MS=650
NBA_USER_AGENT="Mozilla/5.0 ..."

NBA_STATS_BASE_URL and NBA_LIVE_BASE_URL are intentionally configurable so deployments can route through a trusted internal proxy when NBA.com blocks direct server-side requests.

Network Notes

stats.nba.com and sometimes cdn.nba.com can reject requests from cloud, datacenter, VPN, or non-browser TLS fingerprints. In those cases tools return an MCP error with the URL, status code, and response body preview. Run from a residential network or proxy through a service that can reach NBA.com.

Development

npm run typecheck
npm run build

Publish

The package is configured for public npm publishing.

npm login --registry https://registry.npmjs.org
npm publish --dry-run --registry https://registry.npmjs.org
npm publish --registry https://registry.npmjs.org

prepublishOnly runs typecheck and prepack builds dist/.

Smoke test the MCP protocol layer:

node --input-type=module -e "import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; const client = new Client({ name: 'smoke-test', version: '0.0.0' }); const transport = new StdioClientTransport({ command: 'node', args: ['dist/index.js'] }); await client.connect(transport); console.log((await client.listTools()).tools.map(t => t.name)); await client.close();"

Available Tools

15 tools
nba_league_player_statsNBA League Player StatsA
Read-onlyIdempotent

Get league-wide player statistics for a season. Results are limited by default.

Inputs: season (required), limit, teamId, perMode, +4 more.

nba_league_standingsNBA League StandingsC
Read-onlyIdempotent

Get NBA standings for a season and season type.

Inputs: season (required), leagueId, seasonType.

nba_league_team_statsNBA League Team StatsC
Read-onlyIdempotent

Get league-wide team statistics for a season. Results are limited by default.

Inputs: season (required), limit, perMode, leagueId, +3 more.

nba_live_boxscoreNBA Live Box ScoreB
Read-onlyIdempotent

Get the live box score for a 10-digit NBA game id from cdn.nba.com.

Inputs: gameId (required).

nba_live_oddsNBA Live OddsA
Read-onlyIdempotent

Get live betting odds for today's games from cdn.nba.com when available.

Inputs: no named parameters.

nba_live_play_by_playNBA Live Play By PlayA
Read-onlyIdempotent

Get live play-by-play actions for a 10-digit NBA game id from cdn.nba.com.

Inputs: gameId (required).

nba_live_scoreboardNBA Live ScoreboardA
Read-onlyIdempotent

Get today's NBA live scoreboard from cdn.nba.com.

Inputs: no named parameters.

nba_player_career_statsNBA Player Career StatsB
Read-onlyIdempotent

Get career and season totals for an NBA player id.

Inputs: playerId (required), perMode, leagueId.

nba_player_game_logNBA Player Game LogC
Read-onlyIdempotent

Get game-by-game statistics for an NBA player in a season.

Inputs: season (required), playerId (required), limit, dateTo, +3 more.

nba_player_infoNBA Player InfoB
Read-onlyIdempotent

Get biographical and headline information for an NBA player id.

Inputs: playerId (required), leagueId.

nba_schedule_by_dateNBA Schedule By DateB
Read-onlyIdempotent

Get NBA schedule and scores for a specific date via stats.nba.com scoreboardv2.

Inputs: date (required), leagueId.

nba_search_playersSearch NBA PlayersB
Read-onlyIdempotent

Search NBA players by name using stats.nba.com playerindex. Defaults to the supplied season and active players only.

Inputs: query (required), limit, season, leagueId, +2 more.

nba_search_teamsSearch NBA TeamsA
Read-onlyIdempotent

Search NBA teams by name, city, abbreviation, slug, or team id.

Inputs: query.

nba_stats_endpointNBA Stats EndpointC
Read-onlyIdempotent

Advanced raw stats.nba.com endpoint caller. Use a documented endpoint name and NBA parameter names.

Inputs: endpoint (required), params, limitRows.

nba_team_game_logNBA Team Game LogC
Read-onlyIdempotent

Get game-by-game statistics for an NBA team in a season.

Inputs: season (required), teamId (required), limit, dateTo, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of NBA data (player stats, standings, live games, search, etc.) with clear descriptions, minimizing confusion.

    Naming Consistency5/5

    All tools follow a consistent snake_case pattern with 'nba_' prefix and descriptive resource/action names, making them predictable.

    Tool Count5/5

    15 tools is well-scoped for a sports data API, covering essential player, team, game, and schedule operations without excess.

    Completeness4/5

    Core CRUD-like operations are covered (stats, logs, info, search, live). Minor gaps like explicit team roster are mitigated by the raw endpoint.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP Server implementation that integrates the Balldontlie API, to provide information about players, teams and games for the NBA, NFL and MLB.
      4
      86 npm
      26
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing tools to query live scores, schedules, standings, and game stats from the SportRadar API for multiple sports including NFL, NBA, NHL, NCAAMB, soccer, and tennis.
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides access to ESPN Fantasy Basketball APIs, enabling Claude and other MCP clients to fetch league teams, rosters, free agents, matchups, NBA schedules, and live draft assistant tools.
      14
      4
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      MCP server that enables Claude Desktop to access real-time sports data including live scores, fixtures, standings, and NBA statistics using free APIs.
      10
      -