Skip to main content
Glama
deenesjakoruzh
mikechao

balldontlie-mcp

by mikechao
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Balldontlie MCP Server

Trust Score

An MCP Server implementation that integrates the Balldontlie API, to provide information about players, teams and games for the NBA, NFL and MLB.

Tools

  • get_teams

    • Gets the list of team from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)

    • Inputs:

      • league (enum ['NBA', 'NFL', 'MLB']): The sports league to get teams for

  • get_players

    • Gets the list of players from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)

    • Inputs:

      • league (enum ['NBA', 'NFL', 'MLB']): The sports league to get players for

      • firstName (string, optional): The first name of the player to search for

      • lastName (string, optional): The last name of the player to search for

      • cursor (number, optional): Cursor for pagination

  • get_games

    • Gets the list of games from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)

    • Inputs:

      • league (enum ['NBA', 'NFL', 'MLB']): The sports league to get games for

      • dates (string[], optional): Get games for specific dates, format: YYYY-MM-DD

      • teamIds (string[], optional): Get games for specific games

      • cursor (number, optional): Cursor for pagination

  • get_game

    • Get a specific game from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)

    • Inputs:

      • league (enum ['NBA', 'NFL', 'MLB']): The sports league to get the game for

      • gameId (number): The id of the game from the get_games tool

Related MCP server: mlb-api-mcp

Prompts

  • schedule_generator

Given a league (NBA, MLB, NFL), a starting date and ending date generates an interactive schedule in Claude Desktop.

claude desktop example

Sample queries

With this MCP Server installed you can ask Claude or other LLM questions like the following.

Show me today's baseball games.
Can you find football players with the last name Purdy?
How many NBA players have the last name Ming?

Configuration

Getting an API Key

  1. Sign up for account at Balldontlie.io

  2. The free plan is enough for this MCP Server

Installing using Desktop Extension (DXT)

  1. Download the dxt file from the Releases

  2. Open it with Claude Desktop or Go to File -> Settings -> Extensions and drag the .DXT file to the window to install it

Installing via Smithery

To install balldontlie-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @mikechao/balldontlie-mcp --client claude

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcp-servers": {
    "balldontlie": {
      "command": "npx",
      "args": [
        "-y",
        "balldontlie-mcp"
      ],
      "env": {
        "BALLDONTLIE_API_KEY": "YOUR API KEY HERE"
      }
    }
  }
}

Usage with LibreChat

mcpServers:
  balldontlie:
    command: sh
    args:
      - -c
      - BALLDONTLIE_API_KEY=your-api-key-here npx -y balldontlie-mcp

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Disclaimer

This library is not officially associated with balldontlie.io. It is a third-party implementation of the balldontlie api with a MCP Server.

Hosted deployment

A hosted deployment is available on Fronteir AI.

Available Tools

4 tools
get_gameB

Get a specific game from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)

ParametersJSON Schema
NameRequiredDescriptionDefault
leagueYes
gameIdYesGame ID to get the game for, the value should be Game ID from previous call of get_games tool

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description lacks details on behavior like read-only status, authentication, or potential side effects, leaving agents uninformed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence with no redundant information, efficiently conveying the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is too sparse, omitting return values, usage constraints, and other context needed for proper invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one of two parameters (gameId) has a description in the schema; the description does not add meaningful info beyond enumerating leagues and referencing the game ID source.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a specific game from NBA, MLB, or NFL leagues, distinguishing it from siblings like get_games (list) and other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implicitly, the tool is for fetching a single game, but no explicit guidance on when not to use it or alternatives is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_gamesB

Gets the list of games from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)

ParametersJSON Schema
NameRequiredDescriptionDefault
leagueYes
datesNoGet games for a range of dates, format: YYYY-MM-DD, optional
seasonsNoGet games for a specific season, format: YYYY, optional
teamIdsNoGet games for specific team IDs, optional
cursorNoCursor for pagination, the value should be next_cursor from previous call of get_games tool, optional

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description only states read operation but omits pagination behavior (despite cursor param), auth requirements, rate limits, or what happens with no results. No annotations to supplement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single efficient sentence with no fluff. Could be restructured to front-load list nature.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and description does not mention return format. With 5 params, moderate complexity, description should hint at response structure or pagination.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80% so parameters mostly documented. Description adds no extra meaning beyond listing leagues. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Gets the list of games' from specific leagues. Siblings get_game (singular), get_players, get_teams are distinct, so no confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs siblings (e.g., use get_game for a single game). Also no indication of when to use dates vs seasons or cursor.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_playersA

Gets the list of players from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)

ParametersJSON Schema
NameRequiredDescriptionDefault
leagueYes
firstNameNoFirst name of the player to search for, optional
lastNameNoLast name of the player to search for, optional
cursorNoCursor for pagination, the value should be next_cursor from previous call of get_players tool, optional

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully inform about behavior. It only states a read operation without mentioning pagination (cursor parameter exists), rate limits, or other behavioral traits, leaving gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence that efficiently communicates the tool's purpose without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and lack of output schema, the description covers basic purpose but omits context about optional parameters and pagination cursor usage, leaving some completeness gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75% (three of four parameters have descriptions), and the description adds no extra parameter information. Baseline of 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'Gets the list' and resource 'players', and explicitly lists the leagues (NBA, MLB, NFL), distinguishing it from siblings like get_game and get_teams.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving players by league but does not explicitly state when to use this tool over alternatives like get_game or get_teams, nor does it provide exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_teamsA

Gets the list of team from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)

ParametersJSON Schema
NameRequiredDescriptionDefault
leagueYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes a straightforward read operation with no disclosure of authentication, rate limits, or result format. Minimal behavioral context beyond purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence conveys all necessary information without redundancy. Front-loaded with action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simple structure (1 param, no output schema), description covers the core functionality. Could mention return structure (e.g., team names or IDs) but not essential for selection. Minor gap in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has one param 'league' with enum but no description. Description adds meaning by listing the three league values and indicating they serve as selection criteria. Adds value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'gets' and resource 'teams', with specific leagues (NBA, MLB, NFL). Distinguishes from sibling tools (get_game, get_games, get_players) by focusing on team listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Specifies the tool retrieves teams from listed leagues, but no guidance on when to use vs alternatives or when not to use. Implicitly clear but lacks explicit context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • Addedget_game
    • Addedget_games
    • Addedget_players
    • Addedget_teams
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct resource: a single game, list of games, players, or teams. There is no overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with get_ prefix and snake_case. No deviations.

Tool Count5/5

Four tools are well-scoped for a sports data server covering three leagues. Not too many or too few.

Completeness3/5

The server provides only read operations. Missing single-player and single-team retrieval, and no filtering or search capabilities are indicated in descriptions.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MLB V3 Scores MCP Server

    ag2-mcp-servers
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP Server that enables interaction with MLB scores and statistics via the SportsData.io MLB V3 Scores API, allowing users to access baseball data through natural language queries.
    -

  • mlb-api-mcp

    guillochon
    A
    license
    B
    quality
    B
    maintenance
    Python MCP server that provides comprehensive access to MLB statistics and baseball data through a FastAPI-based interface. Acts as a bridge between AI applications and MLB data sources, enabling seamless integration of baseball statistics, game information, player data, and more.
    24
    58
    MIT

  • College Basketball Stats MCP

    ag2-mcp-servers
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for accessing college basketball statistics through the SportsData.io CBB v3 Stats API, enabling AI agents to retrieve and analyze college basketball data through natural language interactions.
    -

  • nba-mcp

    ufo2243
    A
    license
    A
    quality
    C
    maintenance
    MCP server for NBA live data and stats, providing read-only tools to query live scores, box scores, player info, standings, and more from NBA.com.
    15
    9
    1
    MIT

Appeared in Searches