# mikechao/balldontlie-mcp [Health: Active]

**Category:** 🏃 Sports  
**Repository:** https://github.com/mikechao/balldontlie-mcp  
**GitHub Stars:** 26  
**npm Downloads (last month):** 190  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mikechao-balldontlie-mcp

## Description
MCP server that integrates balldontlie api to provide information about players, teams and games for the NBA, NFL and MLB

## Tools
Capabilities this server exposes over MCP:

- **league**
- **firstName**
- **lastName**
- **cursor**
- **dates**
- **teamIds**
- **gameId**

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "balldontlie-mcp": {
    "command": "npx",
    "args": ["-y","balldontlie-mcp"],
    "env": {
      "BALLDONTLIE_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `BALLDONTLIE_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mikechao/balldontlie-mcp MCP server does

The mikechao/balldontlie-mcp MCP server exposes selected Balldontlie API operations through the Model Context Protocol. It covers three leagues: the NBA, MLB, and NFL. Agents can retrieve team lists, search player records, inspect game listings, and fetch an individual game by ID.

The server is suited to questions that need structured league data, such as finding players by surname, checking games on particular dates, or identifying teams in a league. It also includes a `schedule_generator` prompt for Claude Desktop that creates an interactive schedule from a league and a date range.

## How it works

An MCP-compatible client starts the server locally, and the server uses the supplied Balldontlie API key to query the upstream service. Each request specifies a league using one of `NBA`, `MLB`, or `NFL`.

The available operations are exposed as four tools:

- `get_teams` returns teams for a selected league.
- `get_players` returns players and can filter by first name or last name.
- `get_games` returns games and can filter by dates or team IDs.
- `get_game` retrieves one game using its ID.

Player and game list requests accept a numeric cursor for pagination. The `get_game` operation expects an ID obtained from `get_games`.

## Setup and configuration

The mikechao/balldontlie-mcp MCP server requires a Balldontlie account and API key. Set the key in the `BALLDONTLIE_API_KEY` environment variable when starting the server.

For Claude Desktop, configure an MCP server that runs `npx -y balldontlie-mcp` and passes the API key in its environment. The project also provides a DXT release that can be opened or added through Claude Desktop’s Extensions settings. Smithery installation is documented with its CLI and the Claude client option. LibreChat can run the same package through a shell command that sets the key before invoking `npx`.

## Tools and capabilities

The server supports:

- Team discovery across NBA, MLB, and NFL.
- Player lookup by league, with optional first-name and last-name filters.
- Game searches by league, date list, or team ID list.
- Cursor-based pagination for player and game results.
- Individual game retrieval by league and game ID.
- Interactive schedule generation through the documented Claude Desktop prompt.

## Limitations and notes

The mikechao/balldontlie-mcp MCP server is a third-party implementation and is not officially associated with balldontlie.io. Game lookups require an existing game ID, and date filters use `YYYY-MM-DD` values.

_Full upstream README: https://allmcps.com/mcp/mikechao-balldontlie-mcp/readme_