nba-mcp
Provides tools for accessing NBA live data and statistics, including live scoreboards, box scores, play-by-play, player and team information, schedules, standings, and league-wide stats from NBA.com.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nba-mcp get today's live scores"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpRelated 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-mcpFor local development from a checkout:
npm install
npm run build
npm startLocal 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 devTools
nba_stats_endpoint- advanced raw caller for documentedstats.nba.comendpointsnba_search_teams- local static NBA team lookupnba_live_scoreboard- today's live scoreboardnba_live_boxscore- live box score bygameIdnba_live_play_by_play- live play-by-play bygameIdnba_live_odds- today's live odds when availablenba_schedule_by_date- schedule and scores for a datenba_search_players- player search viaplayerindexnba_player_info- player bio and headline statsnba_player_career_stats- player career and season totalsnba_player_game_log- player game log for a seasonnba_team_game_log- team game log for a seasonnba_league_standings- standings by seasonnba_league_player_stats- league-wide player dashboard statsnba_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 buildPublish
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.orgprepublishOnly 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 toolsnba_league_player_statsNBA League Player StatsARead-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 StandingsCRead-onlyIdempotent
Get NBA standings for a season and season type.
Inputs: season (required), leagueId, seasonType.
nba_league_team_statsNBA League Team StatsCRead-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 ScoreBRead-onlyIdempotent
Get the live box score for a 10-digit NBA game id from cdn.nba.com.
Inputs: gameId (required).
nba_live_oddsNBA Live OddsARead-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 PlayARead-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 ScoreboardARead-onlyIdempotent
Get today's NBA live scoreboard from cdn.nba.com.
Inputs: no named parameters.
nba_player_career_statsNBA Player Career StatsBRead-onlyIdempotent
Get career and season totals for an NBA player id.
Inputs: playerId (required), perMode, leagueId.
nba_player_game_logNBA Player Game LogCRead-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 InfoBRead-onlyIdempotent
Get biographical and headline information for an NBA player id.
Inputs: playerId (required), leagueId.
nba_schedule_by_dateNBA Schedule By DateBRead-onlyIdempotent
Get NBA schedule and scores for a specific date via stats.nba.com scoreboardv2.
Inputs: date (required), leagueId.
nba_search_playersSearch NBA PlayersBRead-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 TeamsARead-onlyIdempotent
Search NBA teams by name, city, abbreviation, slug, or team id.
Inputs: query.
nba_stats_endpointNBA Stats EndpointCRead-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 LogCRead-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
Scored across 15 tools
Each tool targets a distinct aspect of NBA data (player stats, standings, live games, search, etc.) with clear descriptions, minimizing confusion.
All tools follow a consistent snake_case pattern with 'nba_' prefix and descriptive resource/action names, making them predictable.
15 tools is well-scoped for a sports data API, covering essential player, team, game, and schedule operations without excess.
Core CRUD-like operations are covered (stats, logs, info, search, live). Minor gaps like explicit team roster are mitigated by the raw endpoint.
Maintenance
Related MCP Connectors
NBA MCP — player, team, and game data via the BallDontLie API
ESPN MCP — keyless multi-sport live scores, teams, and news via ESPN's public site API.
Market data tools for the MCP ecosystem: server stats, events, search, leaderboards, package trends.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP Server implementation that integrates the Balldontlie API, to provide information about players, teams and games for the NBA, NFL and MLB.486 npm26MIT
- FlicenseNot gradedqualityDmaintenanceMCP 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.-
- AlicenseAqualityDmaintenanceAn 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.144MIT
- FlicenseBqualityDmaintenanceMCP server that enables Claude Desktop to access real-time sports data including live scores, fixtures, standings, and NBA statistics using free APIs.10-