NBA Player Stats

A focused Model Context Protocol (MCP) server that provides comprehensive NBA player statistics from basketball-reference.com. This server specializes in delivering detailed player stats including career stats, season comparisons, advanced metrics, shooting stats, and more.

- Features
- Quick Start
- Installation
- Usage
- Available Tools
- Examples
- Basketball Reference Scraper Fixes
- Development Guide
- Known Issues
- Contributing
- License

git clone https://github.com/ziyadmir/nba-player-stats-mcp cd nba-player-stats-mcp

# If installed from PyPI nba-player-stats-server # If running from source python src/server.py

{ "mcpServers": { "nba-player-stats": { "command": "python", "args": ["path/to/basketball/src/server.py"], "cwd": "path/to/basketball" } } }

- Python 3.8 or higher
- pip package manager

The easiest way to install the NBA Player Stats MCP Server:

For development or to get the latest changes:

git clone https://github.com/ziyadmir/nba-player-stats-mcp cd nba-player-stats-mcp

- Create a virtual environment (recommended):

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

pip install -e . # Or with development dependencies pip install -e ".[dev]"

# If installed from PyPI nba-player-stats-server # If running from source python src/server.py

# Import the fix first import fix_basketball_reference from basketball_reference_scraper.players import get_stats # Get LeBron's career per-game stats stats = get_stats('LeBron James', stat_type='PER_GAME', ask_matches=False) # Get specific season stats_2023 = stats[stats['SEASON'] == '2022-23'] # Get playoff stats playoff_stats = get_stats('LeBron James', stat_type='PER_GAME', playoffs=True, ask_matches=False)

Seeexample_usage.pyfor more comprehensive examples.

Get complete career statistics for an NBA player.

- player_name(string, required): The player's name (e.g., "LeBron James")
- stat_type(string, optional): Type of stats - "PER_GAME", "TOTALS", "PER_MINUTE", "PER_POSS", "ADVANCED"

- player_name(string, required): The player's name
- season(integer, required): Season year (e.g., 2023 for 2022-23)
- stat_type(string, optional): Type of stats
- include_playoffs(boolean, optional): Include playoff stats if available

Get advanced statistics (PER, TS%, WS, BPM, VORP, etc.).

- player_name(string, required): The player's name
- season(integer, optional): Specific season, or None for all seasons

Get per-36-minute statistics (pace-adjusted).

- player_name(string, required): The player's name
- season(integer, optional): Specific season, or None for all seasons

Compare statistics between two NBA players.

- player1_name(string, required): First player's name
- player2_name(string, required): Second player's name
- stat_type(string, optional): Type of stats to compare
- season(integer, optional): Specific season, or None for career comparison

Get detailed shooting statistics and splits.

- player_name(string, required): The player's name
- season(integer, optional): Specific season, or None for career stats

- player_name(string, required): The player's name
- season(integer, optional): Specific season, or None for career totals

Get playoff statistics with regular season comparison.

- player_name(string, required): The player's name
- stat_type(string, optional): Type of stats

Get the basketball-reference.com headshot URL.

- player_name(string, required): The player's name

- player_name(string, required): The player's name

Get game-by-game statistics for a specific season.

- player_name(string, required): The player's name
- season(integer, required): Season year (e.g., 2024)
- playoffs(boolean, optional): Whether to get playoff game logs
- date_from(string, optional): Start date in 'YYYY-MM-DD' format
- date_to(string, optional): End date in 'YYYY-MM-DD' format

Get a specific statistic for a player in a given season. Perfect for answering questions like "What was Steph's 3P% in 2018?"

- player_name(string, required): The player's name
- stat_name(string, required): The specific stat (e.g., "PTS", "3P%", "PER")
- season(integer, required): Season year

Get career statistics against a specific team.

- player_name(string, required): The player's name
- team_abbreviation(string, required): Team code (e.g., "GSW", "LAL")
- stat_type(string, optional): Type of stats

- player_name(string, required): The player's name
- award_type(string, optional): "MVP", "DPOY", "ROY", "SMOY", "MIP"

- player_name(string, required): The player's name
- season(integer, required): Season year
- month(string, optional): Specific month or None for all

- player_name(string, required): The player's name
- season(integer, optional): Specific season or None for career

Get detailed playoff statistics for a specific year.

- player_name(string, required): The player's name
- season(integer, required): Season year

Analyze career trends and progression, including year-over-year changes and decline/improvement patterns.

- player_name(string, required): The player's name
- stat_name(string, optional): The stat to analyze trends for (default: "PTS")
- window_size(integer, optional): Years for moving average (default: 3)

Get career high games and milestone performances (40+ point games, 50+ point games, triple-doubles).

- player_name(string, required): The player's name
- threshold_points(integer, optional): Point threshold for high-scoring games (default: 40)
- include_triple_doubles(boolean, optional): Whether to estimate triple-double games

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

- player_name(string, required): The player's name
- season(integer, optional): Specific season or None for career
- split_type(string, optional): "home_away", "rest_days", "monthly", "win_loss"

Get quarter-by-quarter performance, especially 4th quarter and overtime stats.

- player_name(string, required): The player's name
- season(integer, optional): Specific season or None for career
- quarter(string, optional): "1st", "2nd", "3rd", "4th", "OT", or "all"

Track progress toward career milestones with projections for achievement.

- player_name(string, required): The player's name
- milestone_type(string, optional): "points", "assists", "rebounds", "3pm", "games"

Get all-time rankings for a player in various categories.

- player_name(string, required): The player's name
- category(string, optional): "points", "assists", "rebounds", "3pm", "steals", "blocks"

Here are some example questions this MCP server can answer:
- Career Overview: "What are LeBron James' career statistics?"
- Season Comparison: "How did Stephen Curry perform in the 2016 season?"
- Player Comparison: "Compare Michael Jordan and LeBron James career stats"
- Shooting Analysis: "What are Steph Curry's career shooting percentages?"
- Advanced Metrics: "What was Nikola Jokić's PER in 2023?"
- Playoff Performance: "How do Kawhi Leonard's playoff stats compare to regular season?"
- Career Milestones: "What are Kareem Abdul-Jabbar's career highlights?"
- Per-36 Stats: "What are Giannis Antetokounmpo's per-36 minute stats?"
- Specific Stat: "What was Steph Curry's 3-point percentage in 2018?"
- Points Query: "How many points did Stephen Curry average in 2024?"
- Awards: "Where did LeBron James finish in MVP voting in 2020?"
- Game Logs: "Show me Damian Lillard's game log for the 2021 playoffs"
- Vs Team: "What are Kevin Durant's career stats against the Lakers?"
- Monthly: "How did Jayson Tatum perform in December 2023?"
- Clutch: "What are Kyrie Irving's clutch stats for his career?"
- Playoff Year: "How did Jimmy Butler perform in the 2020 playoffs?"
- Career Trends: "Is LeBron James declining with age?"
- Milestone Games: "How many 40-point games does Kevin Durant have?"
- Home/Away: "How does Joel Embiid perform at home vs away?"
- 4th Quarter: "What's Luka Dončić's scoring average in 4th quarters?"
- Milestone Tracking: "When will LeBron pass 40,000 points?"
- All-Time Rankings: "Where does Steph Curry rank all-time in 3-pointers made?"
- Situational: "How does Giannis perform on back-to-backs?"
- Quarter Breakdown: "What percentage of Dame's points come in the 4th?"

- PER_GAME: Traditional per-game averages (points, rebounds, assists, etc.)
- TOTALS: Total statistics for a season or career
- PER_MINUTE: Per-36-minute statistics (normalized for playing time)
- PER_POSS: Per-100-possessions statistics (normalized for pace)
- ADVANCED: Advanced metrics (PER, TS%, WS, BPM, VORP, etc.)

- PER: Player Efficiency Rating
- TS%: True Shooting Percentage
- WS: Win Shares
- BPM: Box Plus/Minus
- VORP: Value Over Replacement Player
- eFG%: Effective Field Goal Percentage
- USG%: Usage Rate
- ORtg: Offensive Rating (points per 100 possessions)
- DRtg: Defensive Rating (points allowed per 100 possessions)
- 3P%: Three-Point Field Goal Percentage
- FT%: Free Throw Percentage
- AST%: Assist Percentage
- REB%: Rebound Percentage

Important: Thebasketball_reference_scraperlibrary has compatibility issues with the current basketball-reference.com website structure. This server includes automatic fixes for these issues.
-

Table ID Changes: Basketball Reference updated their HTML table IDs

- per_game→per_game_stats
- totals→totals_stats
- per_minute→per_minute_stats

Pandas Compatibility: Fixed deprecation warnings withpd.read_html()

Error Handling: Improved handling of missing data and edge cases

The fixes are automatically applied when the server starts via thefix_basketball_reference.pymodule.

The fix involves updating thebasketball_reference_scraper/players.pyfile:
-

Add StringIO import(after BeautifulSoup import):

Update table ID mapping(inget_statsfunction):

# Map old table IDs to new ones table_id_map = { 'per_game': 'per_game_stats', 'totals': 'totals_stats', 'per_minute': 'per_minute_stats', 'per_poss': 'per_poss_stats', 'advanced': 'advanced' }

# Replace: df = pd.read_html(table)[0] df = pd.read_html(StringIO(table))[0]

career_rows = df[df['SEASON']=='Career'].index if len(career_rows) > 0: career_index = career_rows[0] # ... rest of logic