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

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();"