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.

Table of Contents

• 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

1. Clone the repository:

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

2. 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:

1. Clone the repository:

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

2. Create a virtual environment (recommended):

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

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

1. Career Overview: "What are LeBron James' career statistics?"
2. Season Comparison: "How did Stephen Curry perform in the 2016 season?"
3. Player Comparison: "Compare Michael Jordan and LeBron James career stats"
4. Shooting Analysis: "What are Steph Curry's career shooting percentages?"
5. Advanced Metrics: "What was Nikola Jokić's PER in 2023?"
6. Playoff Performance: "How do Kawhi Leonard's playoff stats compare to regular season?"
7. Career Milestones: "What are Kareem Abdul-Jabbar's career highlights?"
8. Per-36 Stats: "What are Giannis Antetokounmpo's per-36 minute stats?"

Deep Analytics Queries (Layer 2)

9. Specific Stat: "What was Steph Curry's 3-point percentage in 2018?"
10. Points Query: "How many points did Stephen Curry average in 2024?"
11. Awards: "Where did LeBron James finish in MVP voting in 2020?"
12. Game Logs: "Show me Damian Lillard's game log for the 2021 playoffs"
13. Vs Team: "What are Kevin Durant's career stats against the Lakers?"
14. Monthly: "How did Jayson Tatum perform in December 2023?"
15. Clutch: "What are Kyrie Irving's clutch stats for his career?"
16. Playoff Year: "How did Jimmy Butler perform in the 2020 playoffs?"

Ultra-Deep Analytics Queries (Layer 3)

17. Career Trends: "Is LeBron James declining with age?"
18. Milestone Games: "How many 40-point games does Kevin Durant have?"
19. Home/Away: "How does Joel Embiid perform at home vs away?"
20. 4th Quarter: "What's Luka Dončić's scoring average in 4th quarters?"
21. Milestone Tracking: "When will LeBron pass 40,000 points?"
22. All-Time Rankings: "Where does Steph Curry rank all-time in 3-pointers made?"
23. Situational: "How does Giannis perform on back-to-backs?"
24. 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

1. Table ID Changes: Basketball Reference updated their HTML table IDs

   • per_game → per_game_stats
   • totals → totals_stats
   • per_minute → per_minute_stats

2. Pandas Compatibility: Fixed deprecation warnings with pd.read_html()

3. 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:

1. Add StringIO import (after BeautifulSoup import):

   from io import StringIO
   

2. 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'
   }
   

3. Fix pandas read_html deprecation:

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

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

1. Create virtual environment:

   python -m venv venv
   source venv/bin/activate
   

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

1. Player Name Variations:

   • Exact match: "LeBron James" ✓
   • Case sensitivity: "lebron james" ✗
   • Partial names: "LeBron" ✗

2. Edge Cases:

   • Retired players
   • Players with no playoff experience
   • Historical players (pre-1973 for advanced stats)

Code Style Guidelines

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

Extending the Server

To add new tools:

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

2. Test thoroughly with various players

3. 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 ⚠️

1. Player Names: Must match basketball-reference.com format exactly

   • ✓ "LeBron James"
   • ✗ "Lebron" or "lebron james"

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

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

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

Contributing Fixes to basketball_reference_scraper

To contribute our fixes back to the original library:

1. Fork: https://github.com/vishaalagartha/basketball_reference_scraper
2. Apply changes from fix_basketball_reference.py
3. Test thoroughly with various players
4. 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.