Log inSubmit server
Balldontlie MCP logo

Balldontlie MCP

by mikechao

Queries Balldontlie for NBA, NFL, and MLB teams, players, and games through MCP tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Balldontlie MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "mikechao-balldontlie-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "balldontlie-mcp"
      ],
      "env": {
        "BALLDONTLIE_API_KEY": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

The mikechao/balldontlie-mcp MCP server connects MCP clients to the Balldontlie API for NBA, NFL, and MLB data. It provides tools to list teams and players, search players by name, find games by date or team, paginate results, and retrieve a specific game. Use it when an agent needs structured professional sports data rather than direct web searches. It requires a Balldontlie API key and can run through a local npx configuration or Claude Desktop installation options.

Use cases

  • List teams in an NBA, MLB, or NFL league
  • Search players by first or last name
  • Find games by date or team ID
  • Retrieve a game from its Balldontlie ID
  • Generate an interactive league schedule in Claude Desktop

Key features

  • Team lookup across NBA, MLB, and NFL
  • Player search with name filters
  • Game search by dates or team IDs
  • Cursor-based pagination
  • Individual game retrieval
  • Claude Desktop schedule prompt

Tools7

What Balldontlie MCP lets your agent do. Expand a tool for its parameters.

Self-reported~12 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

5/5 checks healthy over the last 43d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 1d ago via OSV.dev · balldontlie-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars26Stargazers on the source repository.
npm downloads190Package downloads in the last 30 days.
Last commit7mo agoMost recent push to the default branch.
Tools exposed7Callable tools this server registers over MCP.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Balldontlie MCP works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Balldontlie MCP

mikechao/balldontlie-mcp is an MCP server that connects AI clients to the Balldontlie API for NBA, MLB, and NFL data. Its main tools list teams and players, search players by name, find games by date or team, paginate results, and retrieve a specific game by ID using an API key.

Install it with the documented DXT release, Smithery CLI, or an MCP client configuration that runs `npx -y balldontlie-mcp`. Claude Desktop can open the DXT file or use the provided JSON configuration. Set `BALLDONTLIE_API_KEY` to your Balldontlie API key.

It needs a Balldontlie API key in the `BALLDONTLIE_API_KEY` environment variable.

You can search NBA, MLB, and NFL teams, players, and games. Player searches accept optional first and last names, while game searches support dates and team IDs. Results for players and games can use cursor pagination, and a game can be retrieved by ID.

Yes, it works with Claude Desktop through a local MCP configuration, a DXT extension, or Smithery installation. The project also documents a `schedule_generator` prompt that creates an interactive schedule in Claude Desktop.

Related MCP servers

All in Sports All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewBalldontlie MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/mikechao-balldontlie-mcp?style=directory)](https://allmcps.com/mcp/mikechao-balldontlie-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/mikechao-balldontlie-mcp"><img src="https://allmcps.com/api/badge/mikechao-balldontlie-mcp?style=directory" alt="Balldontlie MCP on AllMCPs" /></a>