NBA Latest Scores MCP Server

Fetches the latest NBA game scores (final or in-progress), including teams, scores, game status, and time remaining, using the free balldontlie public API.

Installation

You can install or run this MCP server via npm or npx:

npm install @dennisk2025/nba-latest-scores
yarn add @dennisk2025/nba-latest-scores
npx @dennisk2025/nba-latest-scores

Adding to Claude Desktop

To use this MCP server in Claude Desktop, add the following entry to your Claude Desktop config file:

{
  "mcpServers": {
    "nba-scores": {
      "command": "npx",
      "args": ["@dennisk2025/nba-latest-scores"]
    }
  }
}

Add this JSON to your Claude Desktop config file at:

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

Restart Claude Desktop after saving your changes.

Usage

This MCP server exposes one tool:

Tool: get_latest_scores

Fetch the latest NBA scores. You can optionally filter by date (YYYY-MM-DD).

Parameters

• date (string, optional): ISO date string (YYYY-MM-DD) to fetch scores for a specific date. Defaults to today (Eastern Time) if not provided.

Returns

A JSON object with the date and an array of games. Each game has:

• id: Game ID (number)
• date: ISO date-time of the game
• status: "final", "in_progress", or "scheduled" (other status strings possible)
• home_team: Full home team name
• home_team_score: Home team score
• visitor_team: Full visitor team name
• visitor_team_score: Visitor team score
• time_remaining: If in progress, string like "4:32 2nd"; otherwise null

Example Tool Calls

Get today's NBA scores:

{
  "tool_name": "get_latest_scores",
  "parameters": {}
}

Get NBA scores for a specific date:

{
  "tool_name": "get_latest_scores",
  "parameters": {
    "date": "2024-03-21"
  }
}

Example Result

{
  "date": "2024-03-21",
  "games": [
    {
      "id": 14654,
      "date": "2024-03-21T23:00:00.000Z",
      "status": "final",
      "home_team": "Miami Heat",
      "home_team_score": 99,
      "visitor_team": "Boston Celtics",
      "visitor_team_score": 105,
      "time_remaining": null
    },
    ...
  ]
}

List of Available Tools

get_latest_scores

• Description: Retrieves a list of the most recent NBA games played, including home and visitor team names, scores, game status (final, in progress), and time left if applicable. Optionally filter by date (YYYY-MM-DD).
• Input:
  • date (string, optional): ISO date string (YYYY-MM-DD) to fetch scores for a specific date. Defaults to today if not provided.
• Output: An object containing the date and an array of game objects as outlined above.

NBA data provided by the free balldontlie.io API.