Skip to main content
Glama

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

Available Tools

29 tools
get_arena_attendanceGet Arena AttendanceC
Read-only

Info about your own arena. Attendance, prices and gate revenue, newest first.

Inputs: team_id (required), limit, offset. Returns: object

get_auctionGet AuctionA
Read-only

Auction of a listed player. Includes more details then what received with search_market_players, including player skills. Use it when the user asks for a player on sale and to compare it with the current people in team. Avoid to abuse of this call for crawling for players. Better filter with search_market_players first in case.

Inputs: player_id (required). Returns: object

get_boxscoreGet BoxscoreB
Read-only

Box score: strategies, ratings, every player's line. Can be received only after the match is over.

Inputs: match_id (required). Returns: object

get_countriesGet CountriesC
Read-only

Every country available in BuzzerBeater.

Inputs: no named parameters. Returns: object

get_country_leaguesGet Country LeaguesB
Read-only

Leagues of a country. level is zero-based (0 = top), division one-based (1 = top); if both are given they must agree.

Inputs: country_id (required), level, limit, offset, +1 more. Returns: object

get_country_national_teamsGet Country National TeamsC
Read-only

Senior and junior national teams of a country, with coaches.

Inputs: country_id (required). Returns: object

get_matchGet MatchB
Read-only

Match header: teams, date, competition, score by period. Box score is not included until the match is overnds.

Inputs: match_id (required), include_boxscore. Returns: object

get_match_eventsGet Match EventsA
Read-only

One page (up to 200) of play-by-play for a finished match. Request is paginated with a cursor, pass nextCursor from the result for the next page. Use it only when the user request it or to get a detailed recap or analysis of a game.

Inputs: match_id (required), cursor. Returns: object

get_match_shootingGet Match ShootingA
Read-only

Shot zones and per-player attempts for a finished match. Use only when explicitly asked for a detailed analysis of a team.

Inputs: match_id (required). Returns: object

get_meGet MeA
Read-only

Current manager: username, supporter flag, owned clubs, coached national teams, granted scopes. Start here for team ids.

Inputs: no named parameters. Returns: object

get_national_team_rosterGet National Team RosterC
Read-only

Called-up squad of a national team. Skills only for the coach.

Inputs: team_id (required). Returns: object

get_national_team_training_historyGet National Team Training HistoryA
Read-only

Squad skill changes from club training of players included in a National team, newest first. Works only for coaches/assistant of said national team, otherwise the request will fail.

Inputs: team_id (required), limit, offset. Returns: object

get_playerGet PlayerB
Read-only

Player page. Includes only public information (age, name, potential, game shape, DMI, etc) and skills only for your own players.

Inputs: player_id (required). Returns: object

get_player_trainingGet Player TrainingA
Read-only

Training sessions of your own player. Require a supporter subscription, or info won't be returned to you.

Inputs: player_id (required), sort. Returns: object

get_seasonsGet SeasonsC
Read-only

Seasons, oldest first.

Inputs: limit, offset. Returns: object

get_standingsGet StandingsB
Read-only

Standings table per group of each stage of a BuzzerBeater competition.

Inputs: competition_id (required), season. Returns: object

get_teamGet TeamC
Read-only

A summary of a club: name, country, manager, league, arena, record.

Inputs: team_id (required). Returns: object

get_team_arenaGet Team ArenaC
Read-only

Public information about a team arena (seats and prices).

Inputs: team_id (required). Returns: object

get_team_economyGet Team EconomyB
Read-only

Economy recap of your own team. Balance, available money, expected sale proceeds and transactions.

Inputs: team_id (required), sort. Returns: object

get_team_facilitiesGet Team FacilitiesB
Read-only

Building available for your own team: levels, max level and weekly upkeep.

Inputs: team_id (required). Returns: object

get_team_rosterGet Team RosterA
Read-only

Give the complete roster of a team. For your own team, you also get the skill values, otherwise you'll get only the public information (name, age, DMI, game shape)

Inputs: team_id (required). Returns: object

get_team_salariesGet Team SalariesB
Read-only

Weekly player and staff salaries of your own team.

Inputs: team_id (required). Returns: object

get_team_scheduleGet Team ScheduleD
Read-only

A club schedule, oldest info come first.

Inputs: team_id (required), limit, offset, season. Returns: object

get_team_staffGet Team StaffC
Read-only

Staff in your own team: role, level, specialty, salary.

Inputs: team_id (required). Returns: object

get_team_statsGet Team StatsC
Read-only

Team statistics for a season. You can get more details with "mode" parameter equal to "Totals".

Inputs: team_id (required), mode, season. Returns: object

get_team_trainingGet Team TrainingC
Read-only

Current training drill and positions of your own team.

Inputs: team_id (required). Returns: object

get_team_training_historyGet Team Training HistoryB
Read-only

Results of past training sessions (skill upgrades and such) of your own team. Non-supporters get the latest session only.

Inputs: team_id (required), sort, limit, offset. Returns: object

scout_teamScout TeamA
Read-only

Scout a club's tactics over its recent games. Use only when explicitly asked to scout a team. Give last_games (1-30, default 10) OR season, not both. Some information might require a supporter subscription.

Inputs: team_id (required), locations (required), match_types (required), season, +1 more. Returns: object

search_market_playersSearch Market PlayersA
Read-only

Search the transfer list with players currently on sale. It does not returns skills, but only public information. Use to scout the market and get a glimpse of what could be a good player(s) based on the request made. More details of a single player can be received via tool get_auction.

filters keys (PascalCase): Min/Max + Age, Height, Salary, Price, Overall, Potential, Experience, GameShape, JumpShot, JumpRange, OutsideDefense, Handling, Driving, Passing, InsideShot, InsideDefense, Rebound, ShotBlock, FreeThrow; plus Country, Position, SecondPosition, Injury (Nothing|OnlyInjured|ExcludeInjured), OnNationalTeam. Level-valued filters (skills, Experience, GameShape) take names like Average, Strong, Prolific, Legendary. More than four skill bounds needs a supporter; eight is the maximum. order_by e.g. AuctionTime, Age, Salary, CurrentBid, Overall, Potential. Searches go at most 150 deep, up to 30 per page.

Inputs: sort, limit, offset, filters, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools target a distinct resource+action, and descriptions clarify the fine distinctions (e.g. get_arena_attendance vs get_team_arena vs get_team_facilities, or get_team_training vs get_team_training_history). The riskiest overlaps are the analytics cluster (get_team_stats, scout_team, get_match_shooting, get_boxscore) and get_team_roster vs get_player, but the "use only when explicitly asked" guidance mitigates misselection.

    Naming Consistency4/5

    Nearly everything follows a snake_case verb_noun pattern (get_*, search_*, scout_*). The one wrinkle is that the get_team_* prefix is overloaded: some of those tools operate on any club (roster, schedule, stats, arena) while others are own-team-only (training, staff, facilities, economy, salaries), and get_arena_attendance sits outside that prefix.

    Tool Count3/5

    29 tools is heavy for a single server and pushes past the comfortable 3-15 range. The domain is genuinely broad (teams, players, market, matches, competitions, countries, national teams) so most tools do map to unique data, but sub-resources like facilities/economy/salaries/staff could plausibly be consolidated into a team-finances or team-info call.

    Completeness4/5

    Coverage of the read surface is strong: team info/roster/schedule/stats/training/finances, market search plus auction detail, match header/boxscore/events/shooting, standings, seasons, countries, leagues and national teams. Notable gaps remain on the player side (no season-by-season player stats or player career/history, no transfer/bid actions) and no league-level fixture listing, but these are minor for a read-only companion API.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables read-only access to Sleeper fantasy sports data, including users, leagues, rosters, matchups, transactions, drafts, players, trending activity, playoff brackets, traded picks, and sport state via MCP tools.
      18
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides read-only access to Sleeper fantasy football data including user info, leagues, rosters, matchups, and NFL state through MCP tools.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables read-only access to DraftKings DFS lobby data, including slates, contests, salaries, and roster rules, via MCP.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables read-only access to public Swedish sports competition data, including federations, districts, schedules, results, standings, team searches, matches by date, and detailed match protocols. It provides these capabilities through MCP tools without requiring login, a browser, or credentials.
      9
      MIT