Nba MCP Server

🚀 NBA MCP Server

A Model Context Protocol (MCP) server implemented in Python, designed to provide NBA statistical data and real-time game data.

🚀 Quick Start

This server offers a set of tools to access NBA data via the NBA API. It serves as a bridge between applications and NBA data services, providing real-time game information and historical statistical data.

✨ Features

• Real-time game data (scoreboard, box score, play-by-play)
• Player information and career statistics
• Team game records and statistics
• League standings
• Game results and schedules

🛠️ Tools

Real-time Game Data

• nba_live_scoreboard

  • Retrieve the real-time scoreboard for NBA games on the current day (either live or the latest).
  • Return game ID, start time, score, and broadcast information.

• nba_live_boxscore

  • Obtain the real-time box score for a specified NBA game ID.
  • Provide detailed player and team statistics.

• nba_live_play_by_play

  • Get the real-time play-by-play actions for a specific game.
  • Include information such as scoring, fouls, timeouts, and substitutions.

Player Information

• nba_common_player_info

  • Fetch the basic information of a player.
  • Include profile, height, weight, team affiliation, and position.

• nba_player_career_stats

  • Retrieve a player's career statistics.
  • Provide statistics in different formats (per-game average, total points, per 36 minutes).

• nba_list_active_players

  • Return a list of all currently active NBA players.

• nba_player_game_logs

  • Obtain a player's game statistics within a specified date range.

Team Data

• nba_team_game_logs_by_name

  • Get a team's game records using the team name.
  • Avoid the need to know the team's numerical ID.

• nba_fetch_game_results

  • Retrieve the game results for a specified team ID and time range.

• nba_team_standings

  • Get the NBA team standings for a specified season and season type.

• nba_team_stats_by_name

  • Obtain team statistics using the team name.
  • Support different aggregation methods (total points, per-game average, etc.).

• nba_all_teams_stats

  • Retrieve the statistical data of all NBA teams across multiple seasons.

Schedule Information

• nba_schedule_and_roster
  • Get the game schedule and team rosters for a specified date.
  • Include game time and matchup information.

💻 Usage Examples

Basic Usage

from nba.mcp_server import NBAMCP

server = NBAMCP()
server.run()

Configuration

Run with Docker

1. Package the image:

   docker build -t nba_mcp_server .
   

2. Start the container:

   docker run -p 8000:8000 nba_mcp_server
   

Run Directly

1. Install dependencies:

   pip install -r requirements.txt
   

2. Execute the script:

   python main.py
   

🔧 Technical Details

This MCP server is implemented based on the following technologies:

• NBA API Python package (nba_api)
• MCP protocol for API interfaces
• Pydantic for input validation
• Pandas for data processing

📄 License

This MCP server is open-source under the MIT License.