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

npm install @balldontlie/mcp-server

Quick Start

1. Get API Key

Sign up at BALLDONTLIE 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:

{
  "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:

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:

{
  "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

Available Tools

NBA (23 tools)

NFL (17 tools)

MLB (14 tools)

EPL (17 tools)

NHL (16 tools)

WNBA (14 tools)

NCAAF (17 tools)

NCAAB (18 tools)

MMA (12 tools)

CS2 (16 tools)

League of Legends (16 tools)

Dota 2 (14 tools)

FIFA World Cup 2026 (6 tools)

La Liga (11 tools)

Serie A (11 tools)

UEFA Champions League (12 tools)

Bundesliga (11 tools)

Ligue 1 (11 tools)

Authentication

The server forwards Authorization headers to the BALLDONTLIE API. Your MCP client should include the API key in requests:

Authorization: YOUR_API_KEY

Error Handling

The server provides detailed error information:

• Authentication Errors (401): Missing or invalid API key
• Authorization Errors (403): Insufficient tier access
• Validation Errors (400): Invalid parameters
• Rate Limiting (429): Request rate exceeded
• Server Errors (5xx): Backend API issues

Development

# Clone and install
git clone <repository>
cd mcp-server
npm install

# Build
npm run build

# Run in development
npm run dev

# Clean build
npm run clean

API Tiers

BALLDONTLIE offers different tiers with varying access levels:

• Free: Basic endpoints (teams, players, games)
• ALL-STAR ($9.99/mo): Includes stats, injuries, standings
• GOAT ($39.99/mo): Full access including advanced stats, box scores, betting odds

Support

• BALLDONTLIE API Documentation
• Discord Community

License

MIT