BALLDONTLIE 体育 API 的远程模型上下文协议服务器。工具目录基于供应商公开的 OpenAPI 规范生成，因此端点方法、路径、参数和约束与 API 源保持一致。

当前生成的桌面包含529种工具，来自27个规范：账户、ATP、德甲、大学棒球、反恐精英、Dota 2、英超、F1、FIFA世界杯、西甲、法甲、英雄联盟、MLB、MLS、MMA、NBA、NCAAB、NCAAF、NCAAW、NFL、NHL、PGA、意甲、UCL、Valorant、WNBA和WTA。/health 报告权威运行时数和部署版本。

认证

每个MCP请求都需要一个BALLDONTLIE API密钥：

初始化、工具列表、认证文档和 API 操作（在 MCP 之外公开）会在继续前验证所提供的密钥。其他工具调用仅将授权头转发给对应的认证 BALLDONTLIE 端点。

公共服务元数据仅限于 /health 和 /.well-known/mcp-config。/api/docs 需要有效的 API 密钥。

敏感账户工具

完整的账户API表面已被注册，但以下工具默认被禁用：

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:

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

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

npm ci
npm run check:openapi
npm test
npm 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.