NBA Player Stats MCP server

NBA Player Stats MCP Server provides comprehensive NBA player statistics from basketball-reference.com, delivering detailed player information including career stats, season comparisons, advanced metrics, shooting stats, and more through the Model Context Protocol (MCP).

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

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. Create a virtual environment (recommended):

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

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

Using the Server

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)

Available Tools

Core Statistics (Layer 1)

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

Deep Analytics Tools (Layer 2)

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.

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

Ultra-Deep Analytics Tools (Layer 3)

18. get_player_career_trends

Analyze career trends and progression.

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.

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.

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.

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.

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"

Example Queries

Basic Queries

• "What are LeBron James' career statistics?"
• "How did Stephen Curry perform in the 2016 season?"
• "Compare Michael Jordan and LeBron James career stats"
• "What are Steph Curry's career shooting percentages?"

Deep Analytics Queries

• "What was Steph Curry's 3-point percentage in 2018?"
• "Where did LeBron James finish in MVP voting in 2020?"
• "Show me Damian Lillard's game log for the 2021 playoffs"
• "What are Kevin Durant's career stats against the Lakers?"

Ultra-Deep Analytics Queries

• "Is LeBron James declining with age?"
• "How many 40-point games does Kevin Durant have?"
• "How does Joel Embiid perform at home vs away?"
• "What's Luka Dončić's scoring average in 4th quarters?"

Stat Types and Glossary

Stat Types

• PER_GAME: Traditional per-game averages
• TOTALS: Total statistics for a season or career
• PER_MINUTE: Per-36-minute statistics
• PER_POSS: Per-100-possessions statistics
• ADVANCED: Advanced metrics (PER, TS%, WS, BPM, VORP)

Key Statistics

• 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

Troubleshooting

Player Not Found

• Use exact names from basketball-reference.com
• Names are case-sensitive

Empty Results

• Check that the player has stats for the requested season
• Verify the player's career span and available statistics

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "nba-player-stats" '{"command":"python","args":["path/to/basketball/src/server.py"],"cwd":"path/to/basketball"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect