# BallDontLie MCP > BallDontLie provides instant access to deep NBA data through one MCP. Pull player profiles, team technical details, and historical game results directly into your AI agent. It lets you audit rosters, calculate season averages, and track scores without manually checking sports websites. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** nba, basketball, sports-statistics, data-retrieval, player-profiles ## Description This connector gives your AI agent direct access to comprehensive basketball data. You can search for thousands of active or retired players, pull specific team technical details, or retrieve the results from past games. Instead of navigating multiple sports sites, your agent acts like a dedicated analyst, pulling together everything you need through natural conversation. If you're running complex analytics, Vinkius makes sure this MCP is easily discoverable alongside thousands of others. Need to track season averages? You can do that. Want to check the roster for all 30 teams? Your agent handles it. It’s about getting reliable basketball intelligence instantly. ## Tools ### get_game_details Pulls all the specific outcomes and stats for a single, given NBA game. ### get_player_details Retrieves comprehensive technical data about any individual NBA player. ### get_team_details Gets the full technical profile and roster information for any NBA team. ### list_games Generates a list of past or upcoming NBA games, including basic scores and dates. ### list_players Searches and lists thousands of NBA players by name, status, or ID. ### list_player_stats Fetches a detailed breakdown of player statistics for one or more specific game matchups. ### list_teams Lists the official names and technical identifiers for all thirty NBA teams. ### get_season_averages Calculates a specific player's performance averages over an entire basketball season. ## Prompt Examples **Prompt:** ``` What are LeBron James's career stats on BallDontLie? ``` **Response:** ``` Searching for LeBron James... I've found his profile (ID: 237). He plays for the Los Angeles Lakers. I can now pull his season averages or specific game stats for you. ``` **Prompt:** ``` Show me the scores for NBA games yesterday. ``` **Response:** ``` Retrieving game results for yesterday... There were 5 games played. Notable results include the Warriors beating the Suns 115-110 and the Celtics winning over the Bucks 120-105. ``` **Prompt:** ``` Get the season averages for player ID 237 in 2023. ``` **Response:** ``` Fetching 2023 season averages for player 237... In that season, they averaged 25.7 points, 7.3 rebounds, and 8.3 assists per game across 71 games played. ``` ## Capabilities ### Retrieve player profiles Search for specific NBA players and pull their full metadata details. ### List all teams Get technical identifying information for every team in the league. ### Find historical game results Retrieve lists of games, including scores and outcomes, filtered by date or season. ### Calculate season performance metrics Determine a player's average points, rebounds, and assists over an entire season. ### Get specific game scores Pull the detailed results and statistics for one particular matchup. ## Use Cases ### A journalist needs last year's key matchup stats. Instead of finding old box scores and manually compiling numbers, the agent runs `list_games` for the desired season. It then uses `get_game_details` on specific dates to pull all necessary player statistics and team totals in one go. ### A fantasy player needs to compare two rivals. The agent runs `list_players` for both athletes. Then, it uses `get_season_averages` on each profile ID to get a clean comparison of their points and rebounds from the last three seasons. ### A data scientist wants all player identifiers. The agent first calls `list_teams` for all available team IDs. Then, it runs `get_team_details` on each ID to build a complete dataset of every unique identifier needed for subsequent statistical modeling. ### Checking the scores from a specific date. The agent uses `list_games`, filtering by yesterday's date. It then asks the client to pull `get_game_details` for the top 3 games listed, giving immediate results without needing multiple API calls. ## Benefits - Stop manually checking stats websites. Instead of jumping between pages, your agent pulls all needed data—whether it's running a query with `list_players` or pulling scores using `list_games`—and gives you one clean answer. - Deep dive into player performance history. Use `get_season_averages` to calculate multi-year trends for any athlete, helping you spot subtle changes in their game that simple stats miss. - Audit team rosters instantly. If you need the full technical details for all 30 teams, use `list_teams` and then check specific squad info with `get_team_details`. It’s fast. - Get the granular picture of a single match. When you run `get_game_details`, you don't just get the final score; you get the underlying statistics for every player involved in that game. - Building complex workflows is easy. You can use `list_games` to find date ranges, then pass those IDs into other tools like `list_player_stats` to build a full report automatically. ## How It Works The bottom line is that you tell the MCP what kind of basketball data you need, and it pulls back the exact metrics without you ever leaving your client environment. 1. Start by listing or searching for a player, team, or date range to narrow down your data scope. 2. The MCP then gathers the necessary unique identifiers (like an ID) and executes the appropriate retrieval function. 3. Your AI agent returns clean, structured data—whether it’s a list of players or specific season averages—ready for use in your application. ## Frequently Asked Questions **How do I use the get_player_details tool with BallDontLie?** You provide the specific player ID and ask for details. The agent will return metadata like their current team, height, and basic bio information. **Can list_games show me scores from last week using BallDontLie?** Yes. You prompt the MCP to use `list_games` and specify a date range. It returns a list of games played, including basic outcomes for those dates. **What is required for get_game_details using BallDontLie?** You must provide the unique ID for a game matchup. This ID usually comes from running `list_games` first so you know which specific game to detail. **Does list_players include retired athletes? (BallDontLie)** Yes, `list_players` can search across both active and retired NBA players. Just specify the player's name or ID in your prompt. **How do I handle authentication when using tools like get_player_details?** You must provide your dedicated BallDontLie API Key within your MCP client settings. Once connected, your agent uses this key to authenticate every request, ensuring secure access to the data. **What specific metrics does the get_season_averages tool return?** The tool returns calculated averages for core performance indicators like points, rebounds, and assists. These figures represent a player's average contribution per game over the specified season. **Are there usage limits when I call list_player_stats frequently?** Yes, the platform manages API usage quotas to ensure stable performance for all users. Refer to the Vinkius documentation for current rate limit details and bulk request guidelines. **How do I find unique identifiers after running list_teams?** The tool lists every NBA team, providing both their technical names and unique IDs. You must capture these specific identifiers to target accurate data retrieval in subsequent calls. **Can I search for a specific player by name?** Yes! Use the `list_players` tool and provide the name in the `search` parameter. Your agent will return a list of matching players with their unique IDs and metadata. **How do I see the scores for all games played on a specific date?** Use the `list_games` tool and provide the date in the `dates` parameter (format YYYY-MM-DD). The response will include all games played on that day with their final scores. **Does the integration provide player season averages?** Absolutely. Use the `get_season_averages` tool by providing the specific season year and the player IDs. This will return averaged performance metrics for the requested period.