io.balldontlie/mcp

Install

Config snippet generator goes here (5 client tabs)

README

# BALLDONTLIE Sports MCP Server

A Model Context Protocol (MCP) server that provides access to comprehensive sports data from the BALLDONTLIE API, including NBA, WNBA, NFL, MLB, EPL, NHL, NCAAF, NCAAB, MMA, CS2, League of Legends, Dota 2, FIFA World Cup 2026, La Liga, Serie A, UEFA Champions League, Bundesliga, and Ligue 1 statistics, player information, game data, and more.

## Features

- **250+ Sports Endpoints**: Complete access to all BALLDONTLIE API endpoints
- **18 Major Sports/Leagues**: NBA, WNBA, NFL, MLB, EPL, NHL, NCAAF, NCAAB, MMA, CS2, League of Legends, Dota 2, FIFA World Cup 2026, La Liga, Serie A, UEFA Champions League, Bundesliga, Ligue 1
- **Comprehensive Data**: Teams, players, games, statistics, standings, injuries, betting odds, and advanced analytics
- **Authentication**: Seamless API key forwarding to backend
- **Pagination**: Full support for cursor-based pagination
- **Error Handling**: Proper error forwarding and handling
- **TypeScript**: Full type safety and IntelliSense support

## Installation

```bash
npm install @balldontlie/mcp-server
```

## Quick Start

### 1. Get API Key

Sign up at [BALLDONTLIE](https://app.balldontlie.io) to get your free API key.

### 2. Configure MCP Client

#### Option A: Use Hosted Remote Server (Recommended)

Add to your MCP client configuration (e.g., Claude Desktop) to use the hosted server:

```json
{
  "mcpServers": {
    "balldontlie-api": {
      "url": "https://mcp.balldontlie.io/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "<YOUR_BALLDONTLIE_API_KEY>"
      }
    }
  }
}
```

Replace `<YOUR_BALLDONTLIE_API_KEY>` with your actual API key from BALLDONTLIE.

#### Option B: Run from Source

Clone and run from source code:

```bash
git clone https://github.com/balldontlie-api/mcp-server.git
cd mcp-server
npm install
npm run build
npm start
```

Configure your MCP client to connect to the local server:

```json
{
  "mcpServers": {
    "balldontlie-api": {
      "url": "http://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "<YOUR_BALLDONTLIE_API_KEY>"
      }
    }
  }
}
```

### 3. Use in Your MCP Client

The server will automatically provide all available tools. You can ask your AI assistant things like:

- "Get the current NBA standings"
- "Show me LeBron James' season stats"
- "What are today's NFL games?"
- "Get Manchester United's recent EPL matches"
- "Show me A'ja Wilson's WNBA season stats"
- "What are the current WNBA standings?"
- "Show me the NCAAB tournament bracket"
- "Get betting odds for tonight's NBA games"

## Environment Variables

| Variable               | Default                      | Description                                            |
| ---------------------- | ---------------------------- | ------------------------------------------------------ |
| `PORT`                 | `3000`                       | Server port when running locally                       |
| `BACKEND_API_URL`      | `https://api.balldontlie.io` | BALLDONTLIE API base URL                               |
| `API_TIMEOUT`          | `30000`                      | Request timeout in milliseconds                        |
| `LOG_LEVEL`            | `info`                       | Logging level (error, warn, info, debug)               |
| `NODE_ENV`             | `development`                | Environment (development, production, test)            |
| `ENABLE_DEBUG`         | `false`                      | Enable debug logging                                   |
| `ENABLE_TRACING`       | `false`                      | Enable DataDog APM tracing (requires DD_AGENT_HOST)    |
| `DD_AGENT_HOST`        | -                            | DataDog agent hostname for APM tracing                 |
| `DD_PROFILING_ENABLED` | `false`                      | Enable DataDog profiling                               |
| `SERVICE_VERSION`      | `1.0.0`                      | Service version for tracing                            |

## Available Tools

### NBA (23 tools)

| Tool                        | Description                       | Parameters                                                                         |
| --------------------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
| `nba_get_teams`             | Get all NBA teams                 | `division`, `conference`                                                           |
| `nba_get_team_by_id`        | Get specific NBA team             | `id` (required)                                                                    |
| `nba_get_players`           | Get NBA players with filters      | `search`, `first_name`, `last_name`, `team_ids`, `player_ids`, pagination          |
| `nba_get_player_by_id`      | Get specific NBA player           | `id` (required)                                                                    |
| `nba_get_active_players`