Balldontlie

io.balldontliePublished by balldontlie.ioOfficial publisherv1.1.0Updated Oct 27, 2026

Provides access to live sports data and analytics from BALLDONTLIE: The Sports API

VerifiedStreamable HTTPWeb executableDeveloper ToolsData & Analytics

Overview

AI-generated overview

Remote MCP server exposing the BALLDONTLIE sports API, letting an assistant query live sports data and analytics across 27 leagues and competitions.

What you can do
  • Query teams, players, games and stats across leagues such as NBA, NFL, MLB, NHL, EPL, F1, PGA, MMA and esports titles
  • Look up league-specific endpoints generated from the vendored OpenAPI specifications (529 tools in total)
  • Read account details through account_get_me, which omits the API key field
  • Optionally use Account tools for signup, API key rotation, subscription changes and billing portal links when enabled by the deployment
When to use it
Useful when an assistant needs structured sports data — scores, rosters, schedules or statistics — from BALLDONTLIE-covered leagues, and you already have or plan to get a BALLDONTLIE API key.
Requirements
A remote streamable HTTP endpoint at mcp.balldontlie.io; no local package. A BALLDONTLIE API key sent as an Authorization bearer header is required for every request, including initialization and tool listing.
Before you install
The API key is a credential passed in the Authorization header; keep it out of shared transcripts. Account tools that create credentials, change billing state or return hosted billing-session URLs are disabled by default and only enabled by a deployment flag, and enabling them can put those values into the conversation. Tool calls forward the Authorization header to the upstream BALLDONTLIE API.

Installation

In SourceWeft

  1. Open Balldontlie in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.balldontlie%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "balldontlie": {
      "type": "http",
      "url": "https://mcp.balldontlie.io/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

BALLDONTLIE MCP Server

Remote Model Context Protocol server for the BALLDONTLIE sports API. The tool catalog is generated from the vendored public OpenAPI specifications so endpoint methods, paths, parameters, and constraints stay aligned with the API source.

The current generated surface contains 529 tools from 27 specifications: Account, ATP, Bundesliga, college baseball, Counter-Strike, Dota 2, EPL, F1, FIFA World Cup, La Liga, Ligue 1, League of Legends, MLB, MLS, MMA, NBA, NCAAB, NCAAF, NCAAW, NFL, NHL, PGA, Serie A, UCL, Valorant, WNBA, and WTA. /health reports the authoritative runtime count and deployed revision.

Authentication

Every MCP request requires a BALLDONTLIE API key:

http
Authorization: Bearer YOUR_API_KEY

Initialization, tool listing, authenticated documentation, and API operations that are public outside the MCP validate the supplied key before proceeding. Other tool calls forward only the Authorization header to the corresponding authenticated BALLDONTLIE endpoint.

Public service metadata is limited to /health and /.well-known/mcp-config. /api/docs requires a valid API key.

Sensitive Account tools

The complete Account API surface is registered, but the following tools are disabled by default:

  • account_signup
  • account_rotate_api_key
  • account_change_subscription
  • account_cancel_subscription
  • account_create_checkout
  • account_get_billing_portal

They can create credentials, change billing state, or return sensitive hosted billing-session URLs. A deployment must set ENABLE_SENSITIVE_ACCOUNT_TOOLS=true exactly to enable them. Enabling the flag means those values may intentionally enter the authenticated caller's MCP transcript. Other spellings, casing, or whitespace fail closed.

account_get_me remains available but always omits the api_key response field.

MCP request example

bash
curl https://mcp.balldontlie.io/mcp \  -H 'Content-Type: application/json' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -d '{    "jsonrpc": "2.0",    "id": 1,    "method": "tools/call",    "params": {      "name": "nba_get_teams",      "arguments": {}    }  }'

Use tools/list to retrieve the current catalog, input schemas, and MCP read-only/destructive annotations.

Development

bash
npm cinpm run check:openapinpm testnpm run build

The tests independently compare every generated operation and input against all vendored specifications. They also cover legacy tool-name compatibility, exact array query serialization, path/body dispatch, credential-safe errors and logs, API-key validation limits, and Account safety controls. Tests never call a live Account mutation.

Updating from the API source

  1. Copy balldontlie-2/marketing/public/openapi.yml to openapi.yml.
  2. Copy every balldontlie-2/marketing/public/openapi/*.yml file into openapi/.
  3. Update scripts/openapi-source.json to the source API commit.
  4. Run npm run generate:openapi.
  5. Run npm test and npm run build.

Generated src/tools/*.ts, src/schemas/*.ts, and registry files are checked in and must not be edited manually. Runtime does not parse YAML and has no production YAML-parser dependency.

Configuration

VariableDefaultPurpose
PORT3000HTTP port
BACKEND_API_URLhttps://api.balldontlie.ioBALLDONTLIE API base URL
API_TIMEOUT30000Upstream timeout in milliseconds
ENABLE_DEBUGfalseLogs only method, query-free path, and query-field count
ENABLE_SENSITIVE_ACCOUNT_TOOLSfalseEnables sensitive Account tools only when exactly true
TRUST_PROXY_HOPS1 in production, 0 otherwiseValidated trusted proxy hop count; only 0 or 1 is accepted
ENABLE_TRACINGfalseEnables Datadog tracing when an agent host is configured

Authorization values, query values, request bodies, raw upstream errors, API-key responses, and hosted billing-session URLs are excluded from server logs and tracing tags.

Source: README.md at commit 861c019

Tools

0
This server asks for a credential such as an API key, so SourceWeft could not read its tools without one and has not indexed them.

Version history

1
  1. v1.1.0LatestSep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Balldontlie integrations

Balldontlie

Published by GitHub account pipeworx-io

Pipeworx gateway connection for balldontlie.io NBA data, letting an assistant look up teams, players, games and stats, plus route other data questions through…

Streamable HTTPWeb executable
Web Search & Scraping52 toolsOct 30, 2026