home / mcp / balldontlie mcp server

Balldontlie MCP Server

Provides access to BALLDONTLIE sports data via an MCP server with API key forwarding and full tooling across multiple leagues.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "balldontlie-api-mcp": {
      "url": "https://mcp.balldontlie.io/mcp",
      "headers": {
        "PORT": "3000",
        "NODE_ENV": "development",
        "LOG_LEVEL": "info",
        "API_TIMEOUT": "30000",
        "ENABLE_DEBUG": "false",
        "DD_AGENT_HOST": "localhost",
        "ENABLE_TRACING": "false",
        "BACKEND_API_URL": "https://api.balldontlie.io",
        "BALLOUT_API_KEY": "YOUR_API_KEY_PLACEHOLDER",
        "SERVICE_VERSION": "1.0.0",
        "DD_PROFILING_ENABLED": "false"
      }
    }
  }
}

You can access BALLDONTLIE sports data through this MCP server, enabling you to query NBA, NFL, MLB, soccer leagues, and more via a unified, authenticated interface. It forwards your API key securely to the BALLDONTLIE backend and provides cursor-based pagination, robust error handling, and full TypeScript support for strong typing and IntelliSense in your client applications.

How to use

You will connect your MCP client to the BALLDONTLIE MCP server to retrieve data such as teams, players, games, standings, and betting odds from a wide range of sports. The server forwards your API key to the backend, so you can access endpoints with the same permissions you have on BALLDONTLIE. Use your MCP client to request information like current standings, player season stats, team rosters, upcoming games, and odds.

How to install

Prerequisites: you need Node.js installed on your machine to run the MCP server locally. You also need an active BALLDONTLIE API key to access the remote data source.

Step 1: Install the MCP server package globally or in your project (examples assume a local project setup).

npm install @balldontlie/mcp-server

Step 2: Start with the hosted remote server (recommended for quick setup). This uses the BALLDONTLIE MCP endpoint and forwards your API key.

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

If you prefer to run from source, clone the repository, install dependencies, build, and start the local server.

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

Step 3: Point your MCP client at the local server. The client should connect to the local endpoint provided by the server and include your API key in the Authorization header.

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

Additional notes

Once connected, your MCP client can request all available tools. Typical queries include standings, player season stats, team rosters, and game schedules across multiple sports.

Security and access

The server forwards Authorization headers to the BALLDONTLIE API. Use a strong API key and never share it publicly. If you encounter authentication issues, verify that your API key is correctly set in the Authorization header.

Troubleshooting

If you see authentication or rate limit errors, ensure your API key is valid and that you are not exceeding the rate limits of BALLDONTLIE. Check that the MCP server is running and that the client is configured to point to the correct URL and port.

Notes on data and endpoints

The MCP server exposes a comprehensive set of endpoints across many sports, including teams, players, games, statistics, standings, injuries, betting odds, and more. The exact tool list is extensive and covers NBA, NFL, MLB, EPL, NHL, WNBA, NCAAF, NCAAB, MMA, CS2, League of Legends, Dota 2, FIFA World Cup 2026, La Liga, Serie A, UEFA Champions League, Bundesliga, and Ligue 1.

Environment and runtime

Environment variables shown in the examples include enabling debug and tracing options, as well as a service version. You can adjust logging with the provided variables to suit your deployment.

Development

To contribute or customize the MCP server, follow the build and development steps to run in development mode, which typically involves building the project and running a development server. Use the standard npm scripts for building and starting the service.

Available tools

nba_get_teams

Get all NBA teams with optional filters for division and conference.

nba_get_team_by_id

Get a specific NBA team by its id.

nba_get_players

Get NBA players with filters such as search terms, team IDs, and pagination.

nba_get_game_by_id

Get details for a specific NBA game by its id.

nba_get_standings

Get NBA team standings for a given season, conference, or division.

nfl_get_teams

Get all NFL teams with optional division and conference filters.

nfl_get_team_by_id

Get a specific NFL team by its id.

nfl_get_players

Get NFL players with filters like search terms, team IDs, position, and pagination.

nfl_get_games

Get NFL games with dates, seasons, weeks, and pagination.

mlb_get_teams

Get all MLB teams with filters for division and league.

mlb_get_team_by_id

Get a specific MLB team by its id.

mlb_get_players

Get MLB players with filters including search terms, team IDs, and pagination.

epl_get_teams

Get all EPL teams with pagination support.

epl_get_team_by_id

Get a specific EPL team by its id.

wnba_get_players

Get WNBA players with filters for search terms and pagination.

wnba_get_game_by_id

Get a specific WNBA game by its id.