Nba Player Stats MCP

🚀 NBA Player Stats MCP Server

A specialized Model Context Protocol (MCP) server that fetches comprehensive NBA player statistics from basketball-reference.com. It offers detailed stats such as career records, season comparisons, advanced metrics, and shooting data.

🚀 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"
    }
  }
}

✨ 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

📦 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 Examples

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.

📚 Documentation

Available Tools

Layer 1: Core Tools

• 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"
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• get_player_headshot_url: Get the basketball - reference.com headshot URL.
  • Parameters:
    • player_name (string, required): The player's name
• get_player_career_highlights: Get career highlights and achievements.
  • Parameters:
    • player_name (string, required): The player's name

Layer 2: Deep Analytics Tools

• 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
• get_player_specific_stat: Get a specific statistic for a player in a given season.
  • 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
• 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
• 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"
• 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
• 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
• 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

• 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)
• 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
• 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"
• 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"
• 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"
• 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

🔧 Technical Details

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.