NBA Player Stats MCP Server

How to use

Use an MCP client to invoke the available statistical tools. You can request career statistics, season-specific stats, advanced metrics, per-36 minute stats, shooting splits, playoff data, and head-to-head comparisons. You can also drill into game logs, monthly splits, clutch performances, and milestone tracking. For example, you can ask for a player’s career PER_GAME stats, look up a specific season’s shooting splits, compare two players side-by-side, or retrieve a player’s playoff statistics alongside their regular-season stats.

How to install

# Prerequisites
# Ensure you have Python 3.8 or higher and pip installed

# Install from PyPI
pip install nba-player-stats-mcp

# Install from source
# 1. Clone the repository or download the source
# 2. Create and activate a virtual environment
python -m venv venv
# On macOS/Linux
source venv/bin/activate
# On Windows
venv\Scripts\activate.bat

# 3. Install in development mode
pip install -e .
# Or with development dependencies
pip install -e .[dev]

# Run the server from PyPI
nba-player-stats-server

# Run the server from source
python src/server.py

Additional content

Configuration and usage details are provided here so you can run the MCP server locally and connect your client to it. If you run the server from Python source, you can start it with python src/server.py. If you install from PyPI, you can start the server with the nba-player-stats-server command. You can also configure a client to connect to the server using the standard MCP configuration shape shown in the example configuration.

Example client configuration (stdio) to run the server locally using Python: you can place this in your MCP client settings.

Examples

Basic career query: retrieve LeBron James’s career stats using the core tools. Seasonal specific query: fetch Stephen Curry’s 2016 season stats. Player comparison: compare Michael Jordan and LeBron James career stats. Per-36 stats: obtain Giannis Antetokounmpo’s per-36 minute stats. Advanced metrics: request Nikola Jokić’s PER and TS%.

Basketball Reference Scraper fixes

This server includes automatic fixes for compatibility issues with basketball-reference_scraper when basketball-reference.com changes its page structure. The fixes adjust table IDs, handle deprecated pandas usage, and improve missing-data handling to keep stat queries reliable.

Known issues and troubleshooting

Some data may be limited for very old seasons or for certain advanced metrics. Names must match basketball-reference.com formatting exactly for accurate results. If you encounter a “No tables found” error, the issue is typically due to site structure changes and can be resolved by the server’s built-in fixes. If a player isn’t found, use exact full names as listed on basketball-reference.com.

Development notes

Set up a local development environment to test new tools or changes. Use a Python virtual environment, install dependencies, and run tests as described in the development workflow. When adding new tools, implement the function in the server code, ensure thorough testing across players, and document any new endpoints.

Notes on tools and endpoints

Tools cover a wide range of data queries, including core statistics retrieval, season-focused stats, advanced metrics, shooting splits, playoff data, game logs, specific stat lookups, and various analytics layers. Each tool is designed to answer common questions about player performance across seasons, matchups, and milestones.

get_player_career_stats

Get complete career statistics for an NBA player using core statistics tools.

get_player_season_stats

Get statistics for a specific season, including season and optional playoff data.

get_player_advanced_stats

Retrieve advanced statistics such as PER, TS%, WS, BPM, and VORP.

get_player_per36_stats

Get per-36-minute statistics (pace-adjusted) for a player.

compare_players

Compare statistics between two players, either career or for a specific season.

get_player_shooting_splits

Get detailed shooting statistics and splits for a player.

get_player_totals

Get total statistics for a season or career (not averages).

get_player_playoff_stats

Get playoff statistics with regular season comparison.

get_player_headshot_url

Retrieve the headshot URL from basketball-reference.com for a player.

get_player_career_highlights

Get career highlights and achievements for a player.

get_player_game_log

Get game-by-game statistics for a specific season, with optional playoffs.

get_player_specific_stat

Get a specific statistic for a player in a given season (e.g., 3P% in 2018).

get_player_vs_team_stats

Retrieve career statistics against a specific NBA team.

get_player_awards_voting

Get awards and voting history for a player.

get_player_monthly_splits

Get statistics broken down by month for a season.

get_player_clutch_stats

Get performance in clutch situations across seasons.

get_player_playoffs_by_year

Get playoff statistics for a specific year for a player.

get_player_career_trends

Analyze year-over-year progression and decline in chosen stats.

get_player_game_highs

Query career-high performances and milestone games (40+ points, triple-doubles).

get_player_situational_splits

Get home/away, rest days, and win/loss situational splits.

get_player_quarter_stats

Get quarter-by-quarter performance statistics including 4th quarter and OT.

get_player_milestone_tracker

Track progress toward career milestones with projections.

get_player_rankings

Retrieve all-time rankings in various stat categories for a player.