bb-mcp

Experimental and unofficial MCP server that wraps the BuzzerBeater public API. It uses BuzzerBeater data but was not made by BuzzerBeater. It is read-only.

Requirements

• Python 3.13+ and uv

• A BuzzerBeater Personal Access Token (PAT), created in the game under Settings → API & third-party apps → Personal tokens

Related MCP server: sleeper_mcp

Tools

• get_me: your manager profile, team ids and granted token scopes (start here)

• get_team: club summary: name, country, league, arena, record

• get_team_roster: a club's players (skills only for your own club)

• get_team_schedule: a club's matches, oldest first

• get_team_stats: team statistics for a season, as averages or totals

• get_team_arena: arena seats and ticket prices

• get_arena_attendance: attendance and gate revenue of your own club

• get_team_training: your club's current training drill

• get_team_training_history: your club's past training sessions

• get_team_staff: your club's staff, levels and salaries

• get_team_facilities: your club's buildings and upkeep

• get_team_economy: your club's balance and transactions

• get_team_salaries: weekly player and staff salaries

• scout_team: a club's tactics over its recent games

• get_player: a player's page (skills only for your own players)

• get_player_training: training sessions of one of your players

• search_market_players: search the transfer list with filters

• get_auction: auction details of a listed player

• get_match: match header: teams, date, score by period

• get_boxscore: box score of a finished match

• get_match_events: play-by-play of a finished match, paged

• get_match_shooting: shot zones and attempts of a finished match

• get_standings: competition standings for a season

• get_seasons: list of seasons

• get_countries: list of countries

• get_country_leagues: leagues of a country, by level or division

• get_country_national_teams: senior and junior national teams of a country

• get_national_team_roster: a national team's called-up squad

• get_national_team_training_history: squad skill changes for a national team you coach

Run

1. Copy .env.example to .env and set BB_PAT (the file explains each variable). .env is gitignored.

2. Install and start:

make sync
make start

The server speaks MCP over stdio, so on its own it just waits for a client. Your AI client normally starts it for you, as described below. In the examples, replace /path/to/bb-mcp with the absolute path of this folder.

Add to Claude Code

claude mcp add bb-mcp -- uv --directory /path/to/bb-mcp run --env-file .env bb-mcp

Or put this in a .mcp.json at the root of your project:

{
  "mcpServers": {
    "bb-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/bb-mcp", "run", "--env-file", ".env", "bb-mcp"]
    }
  }
}

Add to GitHub Copilot (VS Code)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "bb-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/bb-mcp", "run", "--env-file", ".env", "bb-mcp"]
    }
  }
}

Add to Codex

codex mcp add bb-mcp -- uv --directory /path/to/bb-mcp run --env-file .env bb-mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.bb-mcp]
command = "uv"
args = ["--directory", "/path/to/bb-mcp", "run", "--env-file", ".env", "bb-mcp"]