# 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

```bash
npm install -g nba-mcp
```

## Run

Use the published npm package directly from MCP clients:

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

Or run the installed binary:

```bash
nba-mcp
```

For local development from a checkout:

```bash
npm install
npm run build
npm start
```

Local MCP clients can also use the built stdio entrypoint:

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

During development:

```bash
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

```bash
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

```bash
npm run typecheck
npm run build
```

## Publish

The package is configured for public npm publishing.

```bash
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:

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