Skip to main content
Glama

The Blue Alliance MCP Server

A Model Context Protocol (MCP) server that provides access to The Blue Alliance API for FIRST Robotics Competition data. Enables AI assistants and other MCP clients to retrieve comprehensive FRC team, event, and match information.

Features

  • Team Information: Get detailed team profiles, participation history, awards, and media

  • Event Data: Access event details, rankings, matches, and elimination alliances

  • Match Results: Retrieve match data with scores, alliances, and breakdowns

  • Historical Data: Query data from 1992 to the current year

  • Type Safety: All responses validated with Zod schemas

  • Comprehensive Coverage: 35+ tools covering all major TBA API endpoints

Related MCP server: mlb-api-mcp

Installation

npm install -g @withinfocus/tba-mcp-server

Docker

Pull the image from GitHub Container Registry:

docker pull ghcr.io/withinfocus/tba-mcp-server:latest

Or build locally:

git clone https://github.com/withinfocus/tba-mcp-server.git
cd tba-mcp-server
docker build -t tba-mcp-server .

Configuration

  1. Get an API key from The Blue Alliance

  2. Set your API key as an environment variable:

export TBA_API_KEY=your_api_key_here

Or create a .env file:

TBA_API_KEY=your_api_key_here

Usage

With npm

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "tba": {
      "command": "npx",
      "args": ["-y", "@withinfocus/tba-mcp-server"],
      "env": {
        "TBA_API_KEY": "your_api_key_here"
      }
    }
  }
}

With Docker

Add to your MCP client configuration:

{
  "mcpServers": {
    "tba": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--init",
        "-e",
        "TBA_API_KEY=your_api_key_here",
        "ghcr.io/withinfocus/tba-mcp-server:latest"
      ]
    }
  }
}

Or run directly:

docker run --rm -i --init \
  -e TBA_API_KEY=your_api_key_here \
  ghcr.io/withinfocus/tba-mcp-server:latest

Available Tools

Team Information (24 tools)

Access comprehensive team data including profiles, participation history, events, matches, awards, and media.

Key tools: get_team, get_team_events, get_team_matches, get_team_awards, get_team_media

Event Information (19 tools)

Query event details, participants, rankings, matches, and analytics.

Key tools: get_event, get_events, get_event_teams, get_event_rankings, get_event_matches, get_event_oprs

Match Information (3 tools)

Retrieve detailed match data including scores, alliances, and robot tracking.

Key tools: get_match, get_match_simple, get_match_zebra

District Tools (8 tools)

Access district rankings, events, and team information.

Key tools: get_districts, get_district_rankings, get_district_events, get_district_teams

General/Utility Tools (6 tools)

Paginated team listings and API status information.

Key tools: get_teams, get_teams_by_year, get_status

Complete Documentation

  • All Tools - Complete reference for all 35+ tools with parameters and examples

  • Data Schemas - Detailed schema documentation for all response types

Quick Examples

Get team information

// Get detailed team profile
get_team(team_key: "frc86")

// Get team's events in a year
get_team_events(team_key: "frc86", year: 2024)

// Get team's awards
get_team_awards(team_key: "frc86", year: 2024)

Analyze an event

// Get event details
get_event(event_key: "2024casj")

// Get participating teams
get_event_teams(event_key: "2024casj")

// Get rankings
get_event_rankings(event_key: "2024casj")

// Get elimination alliances
get_event_alliances(event_key: "2024casj")

Get match data

// Get detailed match information
get_match(match_key: "2024casj_qm1")

// Get robot tracking data (if available)
get_match_zebra(match_key: "2024casj_qm1")

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, testing guidelines, and how to add new tools.

Available Tools

61 tools
get_district_eventsA
Read-onlyIdempotent

List every FRC event in a district (e.g., all 2024 FIRST in Michigan district qualifying events plus the district championship). Returns full event records. Lighter variants: get_district_events_simple, get_district_events_keys.

Inputs: district_key (required).

get_district_events_keysA
Read-onlyIdempotent

List event keys in an FRC district. Lightest enumeration of district events; ideal for driving per-event lookups across a district season.

Inputs: district_key (required).

get_district_events_simpleA
Read-onlyIdempotent

List events in an FRC district with reduced event fields. Lighter than get_district_events.

Inputs: district_key (required).

get_district_rankingsA
Read-onlyIdempotent

Retrieve season-end district rankings for all teams in an FRC district. Returns each team's overall rank, total district points, rookie bonus, and per-event point breakdown (qualification, alliance, elimination, award, district championship boolean). Determines which teams qualify for the district championship and the FIRST Championship via the district point system.

Inputs: district_key (required).

get_districtsA
Read-onlyIdempotent

List every active FRC district for a given season year (FIRST in Michigan 'fim', New England 'ne', Chesapeake 'chs', Pacific Northwest 'pnw', FIRST In Texas 'fit', Indiana 'in', Ontario 'ont', Israel 'isr', etc.). Returns each district's abbreviation, display name, district key, and year.

Inputs: year (required).

get_district_teamsA
Read-onlyIdempotent

List every team affiliated with an FRC district in a given year. Returns full team profiles. Use to enumerate a district's competitive field. Lighter variants: get_district_teams_simple, get_district_teams_keys.

Inputs: district_key (required).

get_district_teams_keysA
Read-onlyIdempotent

List team keys in an FRC district. Lightest enumeration of a district's teams; ideal for driving per-team lookups.

Inputs: district_key (required).

get_district_teams_simpleA
Read-onlyIdempotent

List teams in an FRC district with reduced team fields. Lighter than get_district_teams.

Inputs: district_key (required).

get_eventA
Read-onlyIdempotent

Retrieve the full record for a single FRC event by event key (e.g., '2023casj' for the 2023 Silicon Valley Regional). Returns event name, code, type (regional/district/championship), location with lat/lng and timezone, date range, district affiliation, week number, webcast channels (Twitch/YouTube), division keys (for championships), parent event key, and playoff type. For a lighter payload see get_event_simple.

Inputs: event_key (required).

get_event_alliancesA
Read-onlyIdempotent

Retrieve playoff alliance selections for an FRC event. Returns each alliance in seed order with captain and pick team keys, declined teams, backup robot info (in/out swap), and playoff progression status (current level, win/loss/tie record, playoff average score, final result string like 'won' or 'eliminated'). Available after alliance selection concludes; null/empty before selection.

Inputs: event_key (required).

get_event_awardsA
Read-onlyIdempotent

List every award given out at a specific FRC event. Returns each award's name, type code, recipient team key, awardee name (for individual honors like Woodie Flowers Finalist or Dean's List), and year. Available once awards ceremony has concluded.

Inputs: event_key (required).

get_event_district_pointsA
Read-onlyIdempotent

Retrieve district championship qualifying points awarded at an event for each participating team. Returns per-team breakdown of qualification points, alliance selection points, elimination points, and award points (the official FIRST district point system) plus tiebreaker stats (highest qual scores, qual wins). Only meaningful for district-affiliated events; non-district events return null.

Inputs: event_key (required).

get_event_insightsA
Read-onlyIdempotent

Retrieve aggregated game-specific statistics computed by The Blue Alliance for an event, separated into qualification and playoff phases. Includes per-task averages, scoring trends, bonus (ranking point) achievement rates, and other game-specific metrics. Field structure varies per game year (e.g., Charged Up, Crescendo, Reefscape).

Inputs: event_key (required).

get_event_matchesA
Read-onlyIdempotent

Fetch every match played at a specific FRC event, including qualification, playoff, and finals. Returns full match records with alliance compositions, final scores, game-specific score breakdown (auto/teleop/endgame components), winning alliance, video links, and timing (scheduled/predicted/actual/post-result). Lighter variants: get_event_matches_simple, get_event_matches_keys.

Inputs: event_key (required).

get_event_matches_keysA
Read-onlyIdempotent

List match keys at an event (strings like '2023casj_qm1', '2023casj_sf1m1'). Lightest enumeration of an event's matches.

Inputs: event_key (required).

get_event_matches_simpleA
Read-onlyIdempotent

List matches at an event with reduced match fields (no game-specific score breakdown or videos). Lighter than get_event_matches.

Inputs: event_key (required).

get_event_oprsA
Read-onlyIdempotent

Retrieve OPR (Offensive Power Rating), DPR (Defensive Power Rating), and CCWM (Calculated Contribution to Winning Margin) for every team at an event, returned as three team_key→number maps. Computed via least-squares regression on match scores. Standard scouting/alliance-selection metrics for estimating per-team contribution.

Inputs: event_key (required).

get_event_predictionsA
Read-onlyIdempotent

Retrieve TBA-generated match score predictions and end-of-event ranking predictions for an event when computed. Returns predicted red/blue scores keyed by match key plus predicted final ranks keyed by team key. Availability and field structure vary by event and game year; some events return null or partial data.

Inputs: event_key (required).

get_event_rankingsA
Read-onlyIdempotent

Retrieve the live or final qualification rankings for an FRC event. Returns ordered ranking rows (team key, rank, win/loss/tie record, matches played, qualification average, sort orders, extra stats, DQ count) plus metadata describing each sort criterion (e.g., Ranking Points, Auto, Endgame). Used to determine alliance selection order, seed playoff alliances, and assess team performance during qualification matches.

Inputs: event_key (required).

get_eventsA
Read-onlyIdempotent

List every FRC event scheduled or completed for a given season year, worldwide. Returns full event records (name, event code, dates, location, district affiliation, week number, webcast channels, event type, division keys for championships, parent event key, playoff type). Use to discover regionals, district qualifying events, district championships, off-season events, and FIRST Championship divisions for a season. Lighter variants: get_events_simple, get_events_keys.

Inputs: year (required).

get_event_simpleA
Read-onlyIdempotent

Retrieve a reduced FRC event profile (key, name, event_code, type, location, dates, year). Lighter than get_event; use when district, webcast, division, and playoff metadata are not needed.

Inputs: event_key (required).

get_events_keysA
Read-onlyIdempotent

List every FRC event key for a season year (strings like '2024casj', '2024nyro', '2024micmp4'). Lightest events enumeration; useful for driving subsequent per-event queries with minimal bandwidth.

Inputs: year (required).

get_events_simpleA
Read-onlyIdempotent

List every FRC event for a season year with reduced event fields. Lighter than get_events.

Inputs: year (required).

get_event_teamsA
Read-onlyIdempotent

List every FRC team registered to compete at a specific event, with full team profiles (number, nickname, name, location, website, motto, rookie year). Use to enumerate the field at a regional, district event, or championship division for scouting or programmatic outreach. Lighter variants: get_event_teams_simple, get_event_teams_keys.

Inputs: event_key (required).

get_event_teams_keysA
Read-onlyIdempotent

List team keys competing at an event (strings like 'frc86'). Lightest enumeration of an event's competing teams; ideal for driving downstream per-team lookups.

Inputs: event_key (required).

get_event_teams_simpleA
Read-onlyIdempotent

List teams competing at an event with reduced team fields (key, team_number, nickname, name, location). Lighter than get_event_teams.

Inputs: event_key (required).

get_matchA
Read-onlyIdempotent

Retrieve the full record for a single match by match key (e.g., '2023casj_qm1'). Returns red/blue alliance compositions (team keys, surrogates, DQ list), final scores, game-specific score breakdown (auto, teleop, endgame, fouls, ranking-point achievements), winning alliance, predicted vs. actual times, and video links. For a lighter payload see get_match_simple. For Zebra MotionWorks robot tracking telemetry see get_match_zebra.

Inputs: match_key (required).

get_match_simpleA
Read-onlyIdempotent

Retrieve a single match with reduced fields (alliances, scores, winning alliance, timing). Omits game-specific score breakdown and video links. Lighter than get_match.

Inputs: match_key (required).

get_match_zebraA
Read-onlyIdempotent

Retrieve Zebra MotionWorks robot-tracking telemetry for a match: per-timestep XY field positions for every robot on red and blue alliances, plus the timestamp series. Only available for events with Zebra tracking installed (typically FIRST Championship divisions and a subset of regionals/district championships). Useful for advanced scouting, defense analysis, and trajectory visualization.

Inputs: match_key (required).

get_statusA
Read-onlyIdempotent

Retrieve TBA API status: current FRC season, max season available, datafeed health flag, list of currently down event keys, max team page index, and minimum/latest mobile app versions for iOS and Android. Useful for sanity-checking the API, discovering season bounds, and detecting outages before issuing other queries.

Inputs: no named parameters.

get_teamA
Read-onlyIdempotent

Retrieve the full profile of a single FIRST Robotics Competition (FRC) team identified by team key (e.g., 'frc86'). Returns team number, nickname, full sponsor/school name, location (city, state/province, country, address, postal code, lat/lng, Google Maps place id), website, motto, rookie year, and home championship affiliation. Use for in-depth team lookups, scouting research, or generating team profile pages. For a lighter response see get_team_simple; for keys only see get_teams_keys.

Inputs: team_key (required).

get_team_awardsA
Read-onlyIdempotent

Retrieve every award won by a team during a single FRC season year. Returns award name, award type code, event key where the award was given, year, and recipient list (team key plus individual awardee for honors like Woodie Flowers Finalist). Useful for tracking annual recognition such as the Impact Award (formerly Chairman's Award), Engineering Inspiration, regional/district event winners, Excellence in Engineering, Innovation in Control, and other technical awards. For lifetime awards see get_team_awards_all.

Inputs: team_key (required), year (required).

get_team_awards_allA
Read-onlyIdempotent

Retrieve every award won by a team across its entire FRC competition history. Returns the full award list (name, year, event key, recipient list, type code). Use for lifetime award tallies, retrospectives, and Hall of Fame analysis. For a single year see get_team_awards.

Inputs: team_key (required).

get_team_districtsA
Read-onlyIdempotent

List the FRC district affiliations a team has held across its history. Returns district records (abbreviation, display name, district key, year). Useful for tracking when a team participated in district play (FIRST in Michigan, New England, Chesapeake, Pacific Northwest, FIRST In Texas, etc.) versus open regional competition, and for analyzing a team's geographic competition history.

Inputs: team_key (required).

get_team_event_awardsA
Read-onlyIdempotent

Retrieve every award won by a specific team at a specific event. Returns award records (name, type, year, recipient list including team key and individual awardee names).

Inputs: team_key (required), event_key (required).

get_team_event_matchesA
Read-onlyIdempotent

Fetch every match a team played at a single specific event in one call. Returns full match records (alliances, scores, score breakdowns, videos, timing). Combines team and event filters server-side, avoiding client-side filtering of get_team_matches or get_event_matches. Lighter variants: get_team_event_matches_simple, get_team_event_matches_keys.

Inputs: team_key (required), event_key (required).

get_team_event_matches_keysA
Read-onlyIdempotent

Lightest variant returning only match keys for a team at a specific event. Ideal for driving downstream per-match queries.

Inputs: team_key (required), event_key (required).

get_team_event_matches_simpleA
Read-onlyIdempotent

Lighter variant of get_team_event_matches: every match a team played at a single event with reduced match fields (no game-specific score breakdown or videos).

Inputs: team_key (required), event_key (required).

get_team_eventsA
Read-onlyIdempotent

List every FRC event a team registered for in a given season year. Returns full event records (name, dates, location, district affiliation, week number, webcasts, event type, division keys). Use to build a team's seasonal schedule or determine which events to scout. Lighter variants: get_team_events_simple, get_team_events_keys.

Inputs: team_key (required), year (required).

get_team_events_allA
Read-onlyIdempotent

List every FRC event a team has competed at across all years it has participated. Returns full event records. Use to map a team's complete competition history, generate timelines, or feed per-event aggregations. For a single year see get_team_events.

Inputs: team_key (required).

get_team_events_keysA
Read-onlyIdempotent

List the event keys a team registered for in a given FRC season year. Lightest variant of get_team_events; useful for driving per-event queries scoped to a team's schedule.

Inputs: team_key (required), year (required).

get_team_events_simpleA
Read-onlyIdempotent

List a team's FRC events in a season year with reduced event fields. Lighter than get_team_events.

Inputs: team_key (required), year (required).

get_team_event_statusA
Read-onlyIdempotent

Retrieve a team's competitive status and standings at a specific event. Returns qualification ranking row (rank, record, sort orders, qual average), alliance selection result (alliance number, pick slot, backup status), playoff progression (level, current-level record, overall record, playoff average, final status), and human-readable summary strings (overall_status_str, alliance_status_str, playoff_status_str), plus next/last match keys. Excellent for live scouting dashboards and event-day status displays.

Inputs: team_key (required), event_key (required).

get_team_event_statusesA
Read-onlyIdempotent

Retrieve a team's per-event status for every event the team attended in a given year, returned as an object keyed by event_key. Each entry mirrors get_team_event_status (rank, alliance, playoff progression, summary strings, next/last match key). Use to render a season status dashboard in one call.

Inputs: team_key (required), year (required).

get_team_historyA
Read-onlyIdempotent

Retrieve a team's full FRC competition history aggregated into a single response: every event, every match, every award, and every robot. High-payload call — use sparingly when a complete archive is needed (e.g., generating a team retrospective). For narrower queries prefer get_team_events_all, get_team_awards_all, or year-scoped variants.

Inputs: team_key (required).

get_team_matchesA
Read-onlyIdempotent

List every qualification, playoff, and finals match a team played during a given FRC season year, across all events. Returns full match records: alliance compositions (red/blue with team keys, surrogates, DQ list), final scores, game-specific score breakdown, winning alliance, video links (YouTube/TBA), and predicted vs. actual times. Lighter variants: get_team_matches_simple (omits score breakdown and videos) and get_team_matches_keys (just match keys).

Inputs: team_key (required), year (required).

get_team_matches_keysA
Read-onlyIdempotent

List every match key a team played in a given FRC season year. Lightest variant of get_team_matches; useful for driving per-match queries scoped to a team's season.

Inputs: team_key (required), year (required).

get_team_matches_simpleA
Read-onlyIdempotent

List every match a team played in a season year with reduced match fields (no game-specific score breakdown or videos). Lighter than get_team_matches.

Inputs: team_key (required), year (required).

get_team_mediaA
Read-onlyIdempotent

Retrieve media (photos, videos, presentations, essays) submitted for a team in a given FRC season year. Returns media records with type (e.g., 'youtube', 'imgur', 'instagram-image', 'cdphotothread'), foreign_key, view URL, direct URL, and the 'preferred' flag highlighting the team's chosen primary image. Useful for surfacing official reveal videos, robot photos, and Impact/Chairman's submissions.

Inputs: team_key (required), year (required).

get_team_media_by_tagA
Read-onlyIdempotent

Retrieve a team's media filtered by a specific TBA tag (e.g., 'chairmans_video', 'chairmans_essay', 'chairmans_presentation', 'imagery') across all years. Useful for surfacing Impact/Chairman's Award submissions or pinned imagery.

Inputs: team_key (required), media_tag (required).

get_team_media_by_tag_yearA
Read-onlyIdempotent

Retrieve a team's media filtered by both tag and season year. Use to fetch a single year's Impact/Chairman's submission package or other tagged media.

Inputs: team_key (required), media_tag (required), year (required).

get_team_robotsA
Read-onlyIdempotent

List the named robots a team has built and registered each year (e.g., 'Stronghold' for 2016, 'Citrus Circuits Quokka' patterns). Returns robot records with year, robot_name, robot key, and team key. Useful for retrospective profiles and historical references.

Inputs: team_key (required).

get_teamsA
Read-onlyIdempotent

List all FRC teams ever registered, paginated in groups of 500. Returns full team profiles. Increment page_num starting at 0 until the response is empty to enumerate every team in TBA's database. For lighter payloads use get_teams_simple; for team keys only use get_teams_keys.

Inputs: page_num (required).

get_teams_by_yearA
Read-onlyIdempotent

List every FRC team that competed in a given season year, paginated in groups of 500. Returns full team profiles. Use to scope team enumeration to a single competition season. Lighter variants: get_teams_by_year_simple, get_teams_by_year_keys.

Inputs: year (required), page_num (required).

get_teams_by_year_keysA
Read-onlyIdempotent

Paginated list of team keys that competed in a given FRC season year. Lightest variant; ideal for building per-year team indices or driving downstream per-team lookups.

Inputs: year (required), page_num (required).

get_teams_by_year_simpleA
Read-onlyIdempotent

Paginated list of FRC teams that competed in a given year with reduced team fields (key, team_number, nickname, name, location). Lighter than get_teams_by_year.

Inputs: year (required), page_num (required).

get_team_simpleA
Read-onlyIdempotent

Retrieve a reduced FRC team profile (key, team_number, nickname, name, city, state_prov, country). Lighter than get_team; use when website, motto, address, and lat/lng are not needed.

Inputs: team_key (required).

get_teams_keysA
Read-onlyIdempotent

Paginated listing of every registered FRC team key only (strings like 'frc86'). Lightest team enumeration option; ideal for building team-key indices or driving subsequent per-team queries with minimal payload size.

Inputs: page_num (required).

get_team_social_mediaA
Read-onlyIdempotent

Retrieve a team's official social media handles registered with The Blue Alliance (Twitter/X, Instagram, Facebook, YouTube channel, GitHub, team website link, etc.). Returned as media records where 'type' is the platform and 'foreign_key' is the handle, slug, or URL fragment.

Inputs: team_key (required).

get_teams_simpleA
Read-onlyIdempotent

Paginated listing of every registered FRC team with reduced fields (key, team_number, nickname, name, city, state_prov, country). Lighter than get_teams; use when website, motto, address, and geocoded location are not needed.

Inputs: page_num (required).

get_team_years_participatedA
Read-onlyIdempotent

Retrieve every season year in which a team has competed in FRC, sorted ascending. Returns a flat array of year integers. Use to bound year-based queries, drive per-year iteration, or determine a team's longevity and rookie year.

Inputs: team_key (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 61 tools

    Disambiguation4/5

    The full/simple/keys variants are consistently documented, so most tools are clearly separated by payload depth and scope. However, the set is large enough that some boundaries are fuzzy—notably get_team_media vs get_team_social_media and get_team_history vs the various _all aggregates—so an agent must read descriptions carefully to avoid misselection.

    Naming Consistency5/5

    Every tool follows the get_<resource>[_scope][_simple|_keys] convention, with uniform use of suffixes to indicate payload size and modifiers like _all, _by_year, and _event. The naming is highly predictable and consistent across all 61 tools.

    Tool Count2/5

    61 tools is a very large surface for an agent to navigate, and most simple/keys variants could have been collapsed into optional result-shaping parameters. While the FRC domain is broad, this count falls well into the too-many range and will slow down tool discovery and selection.

    Completeness5/5

    The read-only FRC domain is covered extremely thoroughly: teams, events, matches, districts, awards, media, rankings, OPR, predictions, statuses, and even robot telemetry all have dedicated tools. There are no obvious dead ends for scouting, research, or live event analysis workflows.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP Server that enables interaction with MLB scores and statistics via the SportsData.io MLB V3 Scores API, allowing users to access baseball data through natural language queries.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Python MCP server that provides comprehensive access to MLB statistics and baseball data through a FastAPI-based interface. Acts as a bridge between AI applications and MLB data sources, enabling seamless integration of baseball statistics, game information, player data, and more.
      24
      59
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for accessing college basketball statistics through the SportsData.io CBB v3 Stats API, enabling AI agents to retrieve and analyze college basketball data through natural language interactions.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Provides access to the Statbotics API for FIRST Robotics Competition statistical data and predictions. Enables AI assistants and other MCP clients to retrieve FRC team EPA ratings, event predictions, and match analytics.
      14
      67 npm
      MIT