bb-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bb-mcp show my team's roster and recent match results"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, recordget_team_roster: a club's players (skills only for your own club)get_team_schedule: a club's matches, oldest firstget_team_stats: team statistics for a season, as averages or totalsget_team_arena: arena seats and ticket pricesget_arena_attendance: attendance and gate revenue of your own clubget_team_training: your club's current training drillget_team_training_history: your club's past training sessionsget_team_staff: your club's staff, levels and salariesget_team_facilities: your club's buildings and upkeepget_team_economy: your club's balance and transactionsget_team_salaries: weekly player and staff salariesscout_team: a club's tactics over its recent gamesget_player: a player's page (skills only for your own players)get_player_training: training sessions of one of your playerssearch_market_players: search the transfer list with filtersget_auction: auction details of a listed playerget_match: match header: teams, date, score by periodget_boxscore: box score of a finished matchget_match_events: play-by-play of a finished match, pagedget_match_shooting: shot zones and attempts of a finished matchget_standings: competition standings for a seasonget_seasons: list of seasonsget_countries: list of countriesget_country_leagues: leagues of a country, by level or divisionget_country_national_teams: senior and junior national teams of a countryget_national_team_roster: a national team's called-up squadget_national_team_training_history: squad skill changes for a national team you coach
Run
Copy
.env.exampleto.envand setBB_PAT(the file explains each variable)..envis gitignored.Install and start:
make sync
make startThe 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-mcpOr 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-mcpOr 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 toolsget_arena_attendanceGet Arena AttendanceCRead-only
Info about your own arena. Attendance, prices and gate revenue, newest first.
Inputs: team_id (required), limit, offset. Returns: object
get_auctionGet AuctionARead-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 BoxscoreBRead-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 CountriesCRead-only
Every country available in BuzzerBeater.
Inputs: no named parameters. Returns: object
get_country_leaguesGet Country LeaguesBRead-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 TeamsCRead-only
Senior and junior national teams of a country, with coaches.
Inputs: country_id (required). Returns: object
get_matchGet MatchBRead-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 EventsARead-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 ShootingARead-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 MeARead-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 RosterCRead-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 HistoryARead-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 PlayerBRead-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 TrainingARead-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 SeasonsCRead-only
Seasons, oldest first.
Inputs: limit, offset. Returns: object
get_standingsGet StandingsBRead-only
Standings table per group of each stage of a BuzzerBeater competition.
Inputs: competition_id (required), season. Returns: object
get_teamGet TeamCRead-only
A summary of a club: name, country, manager, league, arena, record.
Inputs: team_id (required). Returns: object
get_team_arenaGet Team ArenaCRead-only
Public information about a team arena (seats and prices).
Inputs: team_id (required). Returns: object
get_team_economyGet Team EconomyBRead-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 FacilitiesBRead-only
Building available for your own team: levels, max level and weekly upkeep.
Inputs: team_id (required). Returns: object
get_team_rosterGet Team RosterARead-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 SalariesBRead-only
Weekly player and staff salaries of your own team.
Inputs: team_id (required). Returns: object
get_team_scheduleGet Team ScheduleDRead-only
A club schedule, oldest info come first.
Inputs: team_id (required), limit, offset, season. Returns: object
get_team_staffGet Team StaffCRead-only
Staff in your own team: role, level, specialty, salary.
Inputs: team_id (required). Returns: object
get_team_statsGet Team StatsCRead-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 TrainingCRead-only
Current training drill and positions of your own team.
Inputs: team_id (required). Returns: object
get_team_training_historyGet Team Training HistoryBRead-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 TeamARead-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 PlayersARead-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
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
Free, read-only MCP subset of x402 Toolbox's cheap data endpoints, free via MCP.
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Search MCP servers, MCP clients and AI agents, and retrieve listing details. Free, read-only access.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables 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-
- FlicenseNot gradedqualityCmaintenanceProvides read-only access to Sleeper fantasy football data including user info, leagues, rosters, matchups, and NFL state through MCP tools.-
- FlicenseNot gradedqualityCmaintenanceEnables read-only access to DraftKings DFS lobby data, including slates, contests, salaries, and roster rules, via MCP.-
- AlicenseAqualityCmaintenanceEnables 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.9MIT