NBA Player Stats MCP Server

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

Features

This MCP server provides specialized NBA player statistics tools across three layers of depth:

Layer 1: Core Statistics (Tools 1-10)

Career Stats: Complete career statistics with season-by-season breakdowns
Season Stats: Detailed stats for specific seasons including playoffs
Per-Game Averages: Traditional per-game statistics
Total Statistics: Season and career totals (not averages)
Per-36 Minutes: Pace-adjusted per-36-minute statistics
Advanced Metrics: PER, TS%, WS, BPM, VORP, and other efficiency metrics
Player Comparisons: Side-by-side comparisons between two players
Shooting Splits: Detailed shooting percentages and volume stats
Playoff Performance: Complete playoff statistics with regular season comparisons
Career Highlights: Best seasons, milestones, and achievements

Layer 2: Deep Analytics (Tools 11-17)

Game Logs: Game-by-game statistics for detailed analysis
Specific Stat Queries: Get individual stats for any season (e.g., "Steph's 3P% in 2018")
Awards & Voting: MVP, DPOY, and other award voting positions
Vs. Team Stats: Career performance against specific teams
Monthly Splits: Performance broken down by month
Clutch Stats: Performance in close games and pressure situations
Playoff Details: Year-by-year playoff performance

Layer 3: Ultra-Deep Analytics (Tools 18-23)

Career Trends: Year-over-year progression and decline analysis
Game Highs: Career highs, 40+ point games, triple-doubles
Situational Splits: Home/away, rest days, win/loss situations
Quarter Stats: 4th quarter specialization and clutch performance
Milestone Tracking: Progress toward records with projections
All-Time Rankings: Where players rank in NBA history

Additional Features

Player Headshots: Basketball-reference.com player headshot URLs
Multiple Stat Types: PER_GAME, TOTALS, PER_MINUTE, PER_POSS, ADVANCED
Historical Data: Access to historical seasons and career progressions
23 Total Tools: Comprehensive coverage of every conceivable player stat query

Quick Start

Install from PyPI

pip install nba-player-stats-mcp

Install from Source

Clone the repository:

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

Install dependencies:

pip install -r requirements.txt

Running the Server

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Configure Claude Desktop

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

Installation

Prerequisites

Python 3.8 or higher
pip package manager

Install from PyPI

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

pip install nba-player-stats-mcp

Install from Source

For development or to get the latest changes:

Clone the repository:

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

Install in development mode:

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

Usage

Starting the Server

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Python Usage Examples

# 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)

See example_usage.py for more comprehensive examples.

Available Tools

1. `get_player_career_stats`

Get complete career statistics for an NBA player.

Parameters:

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"

2. `get_player_season_stats`

Get statistics for a specific season.

Parameters:

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

3. `get_player_advanced_stats`

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

Parameters:

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

4. `get_player_per36_stats`

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

Parameters:

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

5. `compare_players`

Compare statistics between two NBA players.

Parameters:

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

6. `get_player_shooting_splits`

Get detailed shooting statistics and splits.

Parameters:

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

7. `get_player_totals`

Get total statistics (not averages).

Parameters:

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

8. `get_player_playoff_stats`

Get playoff statistics with regular season comparison.

Parameters:

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

9. `get_player_headshot_url`

Get the basketball-reference.com headshot URL.

Parameters:

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

10. `get_player_career_highlights`

Get career highlights and achievements.

Parameters:

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

Layer 2: Deep Analytics Tools

11. `get_player_game_log`

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

Parameters:

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

12. `get_player_specific_stat`

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

Parameters:

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

13. `get_player_vs_team_stats`

Get career statistics against a specific team.

Parameters:

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

14. `get_player_awards_voting`

Get awards and voting history.

Parameters:

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

15. `get_player_monthly_splits`

Get statistics broken down by month.

Parameters:

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

16. `get_player_clutch_stats`

Get performance in clutch situations.

Parameters:

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

17. `get_player_playoffs_by_year`

Get detailed playoff statistics for a specific year.

Parameters:

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

Layer 3: Ultra-Deep Analytics Tools

18. `get_player_career_trends`

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

Parameters:

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)

19. `get_player_game_highs`

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

Parameters:

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

20. `get_player_situational_splits`

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

Parameters:

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"

21. `get_player_quarter_stats`

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

Parameters:

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"

22. `get_player_milestone_tracker`

Track progress toward career milestones with projections for achievement.

Parameters:

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

23. `get_player_rankings`

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

Parameters:

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

Examples

Here are some example questions this MCP server can answer:

Basic Queries (Layer 1)

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?"

Deep Analytics Queries (Layer 2)

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?"

Ultra-Deep Analytics Queries (Layer 3)

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?"

Stat Type Explanations

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.)

Key Statistics Glossary

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

Basketball Reference Scraper Fixes

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

Issues Fixed

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 with pd.read_html()
Error Handling: Improved handling of missing data and edge cases

The fixes are automatically applied when the server starts via the fix_basketball_reference.py module.

Complete Fix Details

The fix involves updating the basketball_reference_scraper/players.py file:

Add StringIO import (after BeautifulSoup import):
```
from io import StringIO
```

Update table ID mapping (in get_stats function):

# 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'
}

Fix pandas read_html deprecation:

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

Handle missing Career row:

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

To contribute these fixes back to the original library, see the Contributing section.

Development Guide

Setting Up Development Environment

Create virtual environment:

python -m venv venv
source venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test
pytest tests/test_integration.py -v

Manual Testing

Test the fix module:

python example_usage.py

Common Test Cases

Player Name Variations:
- Exact match: "LeBron James" ✓
- Case sensitivity: "lebron james" ✗
- Partial names: "LeBron" ✗
Edge Cases:
- Retired players
- Players with no playoff experience
- Historical players (pre-1973 for advanced stats)

Code Style Guidelines

Python Style: Follow PEP 8
Error Handling: Always catch specific exceptions
Data Processing: Check for empty results before accessing

Extending the Server

To add new tools:

Create function in server.py:

@mcp.tool()
async def get_player_new_stat(
    player_name: str,
    **kwargs
) -> Dict[str, Any]:
    """Tool description"""
    try:
        # Implementation
        pass
    except Exception as e:
        logger.error(f"Error: {e}")
        return {"error": str(e)}

Test thoroughly with various players
Update this README with new tool documentation

Known Issues

Working Features ✅

All player statistics tools function correctly with the fixes applied
Player headshot URLs work reliably

Limitations ⚠️

Player Names: Must match basketball-reference.com format exactly
- ✓ "LeBron James"
- ✗ "Lebron" or "lebron james"
Historical Data: Some features may have limited data for older seasons
- Advanced stats not available before 1973-74
- Some shooting stats missing for early careers
Library Limitations: The underlying basketball_reference_scraper has:
- No active maintenance
- Inconsistent error handling
- Limited documentation

Troubleshooting

"No tables found" Error

Cause: Website structure changed
Fix: Applied automatically by fix_basketball_reference.py

Player Not Found

Cause: Incorrect name format
Solution: Use exact names from basketball-reference.com

Empty Results

Cause: Player has no stats for requested type/season
Solution: Check player's career span and stat availability

Testing

Run the test suite:

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

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Contributing Fixes to basketball_reference_scraper

To contribute our fixes back to the original library:

Fork: https://github.com/vishaalagartha/basketball_reference_scraper
Apply changes from fix_basketball_reference.py
Test thoroughly with various players
Submit PR: "Fix table parsing for updated basketball-reference.com structure"

Changelog

Version 0.3.0 (Latest)

Added Layer 3 ultra-deep analytics tools (6 new tools)
Career trend analysis with year-over-year progression
Game highs and milestone tracking (40+ pt games, triple-doubles)
Situational splits (home/away, rest days, wins/losses)
Quarter-by-quarter performance analysis
Milestone projections and all-time rankings
Now includes 23 total tools across 3 layers

Version 0.2.0

Added Layer 2 deep analytics tools (7 new tools)
Game logs and specific stat queries
Awards and voting history support
Team matchup statistics
Monthly and temporal splits
Clutch performance metrics
Enhanced playoff year-by-year analysis

Version 0.1.0

Initial release with 10 core player statistics tools
Basketball-reference.com compatibility fixes
Career, season, and advanced statistics

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Data sourced from basketball-reference.com
Built using the basketball_reference_scraper library
Implements the Model Context Protocol
Uses FastMCP framework

Support

For issues and feature requests, please use the GitHub issue tracker.

NBA Player Stats MCP Server

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

Features

This MCP server provides specialized NBA player statistics tools across three layers of depth:

Layer 1: Core Statistics (Tools 1-10)

Career Stats: Complete career statistics with season-by-season breakdowns
Season Stats: Detailed stats for specific seasons including playoffs
Per-Game Averages: Traditional per-game statistics
Total Statistics: Season and career totals (not averages)
Per-36 Minutes: Pace-adjusted per-36-minute statistics
Advanced Metrics: PER, TS%, WS, BPM, VORP, and other efficiency metrics
Player Comparisons: Side-by-side comparisons between two players
Shooting Splits: Detailed shooting percentages and volume stats
Playoff Performance: Complete playoff statistics with regular season comparisons
Career Highlights: Best seasons, milestones, and achievements

Layer 2: Deep Analytics (Tools 11-17)

Game Logs: Game-by-game statistics for detailed analysis
Specific Stat Queries: Get individual stats for any season (e.g., "Steph's 3P% in 2018")
Awards & Voting: MVP, DPOY, and other award voting positions
Vs. Team Stats: Career performance against specific teams
Monthly Splits: Performance broken down by month
Clutch Stats: Performance in close games and pressure situations
Playoff Details: Year-by-year playoff performance

Layer 3: Ultra-Deep Analytics (Tools 18-23)

Career Trends: Year-over-year progression and decline analysis
Game Highs: Career highs, 40+ point games, triple-doubles
Situational Splits: Home/away, rest days, win/loss situations
Quarter Stats: 4th quarter specialization and clutch performance
Milestone Tracking: Progress toward records with projections
All-Time Rankings: Where players rank in NBA history

Additional Features

Player Headshots: Basketball-reference.com player headshot URLs
Multiple Stat Types: PER_GAME, TOTALS, PER_MINUTE, PER_POSS, ADVANCED
Historical Data: Access to historical seasons and career progressions
23 Total Tools: Comprehensive coverage of every conceivable player stat query

Quick Start

Install from PyPI

pip install nba-player-stats-mcp

Install from Source

Clone the repository:

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

Install dependencies:

pip install -r requirements.txt

Running the Server

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Configure Claude Desktop

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

Installation

Prerequisites

Python 3.8 or higher
pip package manager

Install from PyPI

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

pip install nba-player-stats-mcp

Install from Source

For development or to get the latest changes:

Clone the repository:

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

Install in development mode:

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

Usage

Starting the Server

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Python Usage Examples

# 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)

See example_usage.py for more comprehensive examples.

Available Tools

1. `get_player_career_stats`

Get complete career statistics for an NBA player.

Parameters:

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"

2. `get_player_season_stats`

Get statistics for a specific season.

Parameters:

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

3. `get_player_advanced_stats`

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

Parameters:

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

4. `get_player_per36_stats`

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

Parameters:

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

5. `compare_players`

Compare statistics between two NBA players.

Parameters:

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

6. `get_player_shooting_splits`

Get detailed shooting statistics and splits.

Parameters:

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

7. `get_player_totals`

Get total statistics (not averages).

Parameters:

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

8. `get_player_playoff_stats`

Get playoff statistics with regular season comparison.

Parameters:

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

9. `get_player_headshot_url`

Get the basketball-reference.com headshot URL.

Parameters:

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

10. `get_player_career_highlights`

Get career highlights and achievements.

Parameters:

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

Layer 2: Deep Analytics Tools

11. `get_player_game_log`

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

Parameters:

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

12. `get_player_specific_stat`

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

Parameters:

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

13. `get_player_vs_team_stats`

Get career statistics against a specific team.

Parameters:

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

14. `get_player_awards_voting`

Get awards and voting history.

Parameters:

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

15. `get_player_monthly_splits`

Get statistics broken down by month.

Parameters:

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

16. `get_player_clutch_stats`

Get performance in clutch situations.

Parameters:

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

17. `get_player_playoffs_by_year`

Get detailed playoff statistics for a specific year.

Parameters:

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

Layer 3: Ultra-Deep Analytics Tools

18. `get_player_career_trends`

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

Parameters:

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)

19. `get_player_game_highs`

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

Parameters:

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

20. `get_player_situational_splits`

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

Parameters:

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"

21. `get_player_quarter_stats`

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

Parameters:

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"

22. `get_player_milestone_tracker`

Track progress toward career milestones with projections for achievement.

Parameters:

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

23. `get_player_rankings`

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

Parameters:

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

Examples

Here are some example questions this MCP server can answer:

Basic Queries (Layer 1)

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?"

Deep Analytics Queries (Layer 2)

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?"

Ultra-Deep Analytics Queries (Layer 3)

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?"

Stat Type Explanations

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.)

Key Statistics Glossary

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

Basketball Reference Scraper Fixes

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

Issues Fixed

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 with pd.read_html()
Error Handling: Improved handling of missing data and edge cases

The fixes are automatically applied when the server starts via the fix_basketball_reference.py module.

Complete Fix Details

The fix involves updating the basketball_reference_scraper/players.py file:

Add StringIO import (after BeautifulSoup import):
```
from io import StringIO
```

Update table ID mapping (in get_stats function):

# 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'
}

Fix pandas read_html deprecation:

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

Handle missing Career row:

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

To contribute these fixes back to the original library, see the Contributing section.

Development Guide

Setting Up Development Environment

Create virtual environment:

python -m venv venv
source venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test
pytest tests/test_integration.py -v

Manual Testing

Test the fix module:

python example_usage.py

Common Test Cases

Player Name Variations:
- Exact match: "LeBron James" ✓
- Case sensitivity: "lebron james" ✗
- Partial names: "LeBron" ✗
Edge Cases:
- Retired players
- Players with no playoff experience
- Historical players (pre-1973 for advanced stats)

Code Style Guidelines

Python Style: Follow PEP 8
Error Handling: Always catch specific exceptions
Data Processing: Check for empty results before accessing

Extending the Server

To add new tools:

Create function in server.py:

@mcp.tool()
async def get_player_new_stat(
    player_name: str,
    **kwargs
) -> Dict[str, Any]:
    """Tool description"""
    try:
        # Implementation
        pass
    except Exception as e:
        logger.error(f"Error: {e}")
        return {"error": str(e)}

Test thoroughly with various players
Update this README with new tool documentation

Known Issues

Working Features ✅

All player statistics tools function correctly with the fixes applied
Player headshot URLs work reliably

Limitations ⚠️

Player Names: Must match basketball-reference.com format exactly
- ✓ "LeBron James"
- ✗ "Lebron" or "lebron james"
Historical Data: Some features may have limited data for older seasons
- Advanced stats not available before 1973-74
- Some shooting stats missing for early careers
Library Limitations: The underlying basketball_reference_scraper has:
- No active maintenance
- Inconsistent error handling
- Limited documentation

Troubleshooting

"No tables found" Error

Cause: Website structure changed
Fix: Applied automatically by fix_basketball_reference.py

Player Not Found

Cause: Incorrect name format
Solution: Use exact names from basketball-reference.com

Empty Results

Cause: Player has no stats for requested type/season
Solution: Check player's career span and stat availability

Testing

Run the test suite:

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

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Contributing Fixes to basketball_reference_scraper

To contribute our fixes back to the original library:

Fork: https://github.com/vishaalagartha/basketball_reference_scraper
Apply changes from fix_basketball_reference.py
Test thoroughly with various players
Submit PR: "Fix table parsing for updated basketball-reference.com structure"

Changelog

Version 0.3.0 (Latest)

Added Layer 3 ultra-deep analytics tools (6 new tools)
Career trend analysis with year-over-year progression
Game highs and milestone tracking (40+ pt games, triple-doubles)
Situational splits (home/away, rest days, wins/losses)
Quarter-by-quarter performance analysis
Milestone projections and all-time rankings
Now includes 23 total tools across 3 layers

Version 0.2.0

Added Layer 2 deep analytics tools (7 new tools)
Game logs and specific stat queries
Awards and voting history support
Team matchup statistics
Monthly and temporal splits
Clutch performance metrics
Enhanced playoff year-by-year analysis

Version 0.1.0

Initial release with 10 core player statistics tools
Basketball-reference.com compatibility fixes
Career, season, and advanced statistics

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Data sourced from basketball-reference.com
Built using the basketball_reference_scraper library
Implements the Model Context Protocol
Uses FastMCP framework

Support

For issues and feature requests, please use the GitHub issue tracker.

NBA Player Stats MCP Server

NBA Player Stats MCP Server

Table of Contents

Features

Layer 1: Core Statistics (Tools 1-10)

Layer 2: Deep Analytics (Tools 11-17)

Layer 3: Ultra-Deep Analytics (Tools 18-23)

Additional Features

Quick Start

Install from PyPI

Install from Source

Running the Server

Configure Claude Desktop

Installation

Prerequisites

Install from PyPI

Install from Source

Usage

Starting the Server

Python Usage Examples

Available Tools

1. get_player_career_stats

2. get_player_season_stats

3. get_player_advanced_stats

4. get_player_per36_stats

5. compare_players

6. get_player_shooting_splits

7. get_player_totals

8. get_player_playoff_stats

9. get_player_headshot_url

10. get_player_career_highlights

Layer 2: Deep Analytics Tools

11. get_player_game_log

12. get_player_specific_stat

13. get_player_vs_team_stats

14. get_player_awards_voting

15. get_player_monthly_splits

16. get_player_clutch_stats

17. get_player_playoffs_by_year

Layer 3: Ultra-Deep Analytics Tools

18. get_player_career_trends

19. get_player_game_highs

20. get_player_situational_splits

21. get_player_quarter_stats

22. get_player_milestone_tracker

23. get_player_rankings

Examples

Basic Queries (Layer 1)

Deep Analytics Queries (Layer 2)

Ultra-Deep Analytics Queries (Layer 3)

Stat Type Explanations

Key Statistics Glossary

Basketball Reference Scraper Fixes

Issues Fixed

Complete Fix Details

Development Guide

Setting Up Development Environment

Testing

Manual Testing

Common Test Cases

Code Style Guidelines

Extending the Server

Known Issues

Working Features ✅

Limitations ⚠️

Troubleshooting

Testing

Contributing

Contributing Fixes to basketball_reference_scraper

Changelog

Version 0.3.0 (Latest)

Version 0.2.0

Version 0.1.0

License

Acknowledgments

Support

NBA Player Stats MCP Server

Table of Contents

Features

Layer 1: Core Statistics (Tools 1-10)

1. `get_player_career_stats`

2. `get_player_season_stats`

3. `get_player_advanced_stats`

4. `get_player_per36_stats`

5. `compare_players`

6. `get_player_shooting_splits`

7. `get_player_totals`

8. `get_player_playoff_stats`

9. `get_player_headshot_url`

10. `get_player_career_highlights`

11. `get_player_game_log`

12. `get_player_specific_stat`

13. `get_player_vs_team_stats`

14. `get_player_awards_voting`

15. `get_player_monthly_splits`

16. `get_player_clutch_stats`

17. `get_player_playoffs_by_year`

18. `get_player_career_trends`

19. `get_player_game_highs`

20. `get_player_situational_splits`

21. `get_player_quarter_stats`

22. `get_player_milestone_tracker`

23. `get_player_rankings`

1. `get_player_career_stats`

2. `get_player_season_stats`

3. `get_player_advanced_stats`

4. `get_player_per36_stats`

5. `compare_players`

6. `get_player_shooting_splits`

7. `get_player_totals`

8. `get_player_playoff_stats`

9. `get_player_headshot_url`

10. `get_player_career_highlights`

11. `get_player_game_log`

12. `get_player_specific_stat`

13. `get_player_vs_team_stats`

14. `get_player_awards_voting`

15. `get_player_monthly_splits`

16. `get_player_clutch_stats`

17. `get_player_playoffs_by_year`

18. `get_player_career_trends`

19. `get_player_game_highs`

20. `get_player_situational_splits`

21. `get_player_quarter_stats`

22. `get_player_milestone_tracker`

23. `get_player_rankings`