NBA

The NBA MCP Server provides live NBA data through nba_api for use by LLMs. You can query current game scores, player and team statistics, game logs, standings, and more through structured endpoints and simple, configurable runtime options.

How to use

You connect to the NBA MCP Server from your MCP client to fetch live game data, player stats, team stats, and standings. Choose between local runtime (stdio) or a hosted runtime (http) based on how you want to run the server. After starting, you perform requests to the available endpoints to retrieve data such as today’s scoreboard, player career stats, team game logs, and league standings. Use the provided tools to pull detailed statistics and live game information, then feed the results into your workflows or chat integrations.

Two common ways to run the server are available. First, run the server locally with the runtimes shown below. Second, run a prebuilt container for quick access. In both cases, you expose the same functional endpoints for retrieving NBA data.

Practical usage patterns you can implement:

• Retrieve today’s NBA scoreboard to surface live game statuses and basic team information.
• Fetch a player’s career stats or recent game logs for analysis or summarization.
• Pull team year-by-year stats or league standings to compare historical performance.
• Obtain live play-by-play data for a current game and present it in a narrative or dashboard format.

How to install

Prerequisites: you need Python installed on your system if you plan to run the server locally with the uv runtime. You also need Docker if you plan to run the official container image.

Option A: Run locally using uv (stdio runtime) Prepare a folder containing your server script and run the server with the provided runtime command.

Directory-based run configuration (example): use your own absolute path for the directory that contains the server script.

{
  "mcpServers": {
    "nba_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/nba_mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Option B: Run with Docker (stdio runtime)

If you prefer a container, you can run the prebuilt image directly.

{
  "mcpServers": {
    "nba_mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "stevenyuser/nba_mcp"
      ]
    }
  }
}

Additional notes

Environment variables are not required for the default operation shown, but you can extend configurations with environment variables if needed. If you plan to run multiple instances or customize data sources, you can adjust the runtime directory or container options accordingly.

Available tools

get_player_career_stats

Retrieves comprehensive career statistics for a player identified by player_id.

get_player_awards

Fetches all awards and achievements for a player, including MVPs, All-Star selections, and championships.

get_player_game_log

Provides game-by-game statistics and results for a player for a given season and season_type.

get_team_details

Returns comprehensive team information including championships, awards, history, and background.

get_team_year_by_year_stats

Gives historical, year-by-year team performance statistics.

get_team_game_log

Delivers team game-by-game statistics and results for a given season and season_type.

get_league_team_standings

Provides standings for all teams in the league by season.

get_today_scoreboard

Retrieves today’s NBA games with live scores and statuses.

get_live_game_boxscore

Fetches live game data including scores, player stats, and timeouts for a specific game.

get_live_game_play_by_play

Retrieves live play-by-play data for a game.

nba://players

Returns a list of all NBA players, past and present.

nba://active_players

Returns a list of currently active NBA players.

nba://teams

Returns a list of all NBA teams.