TBA

The Blue Alliance MCP Server provides access to The Blue Alliance API for FIRST Robotics Competition data, enabling AI assistants and other MCP clients to retrieve team, event, and match information with type-safe responses and broad coverage across the API.

How to use

You use the MCP server by connecting your MCP client to one or more local or remote server configurations. The server exposes a range of endpoints that let you fetch team profiles, events, rankings, matches, and historical data, all validated for correctness. You can integrate these tools into your workflows, assistants, or automation to quickly access FRC data.

How to install

Prerequisites: you need Node.js installed for the npm-based workflow and Docker if you prefer running the server in a container.

Install using npm (recommended): you install the MCP server globally so you can reference it from any MCP client.

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

Install using Docker: pull the latest image from the GitHub Container Registry or build locally.

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

If you prefer to build locally, clone the repository and build the image.

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

Configuration and running

You must provide an API key from The Blue Alliance. Set it in your environment or in a .env file before starting the server.

Environment variable for API key:

export TBA_API_KEY=your_api_key_here

Alternatively, place the key in a .env file in the running directory with the following content:

TBA_API_KEY=your_api_key_here

Examples of starting the server with common runtimes

Using npm via npx to run the MCP server directly in your environment: you can specify the API key through the environment.

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

Notes on security

Protect your API key. Do not commit keys into source control and use per-environment keys where possible.

Available tools

get_team

Retrieve a detailed team profile including participation history, awards, and media.

get_team_events

Fetch all events for a given team in a specified year or range.

get_team_matches

Get matches involving a specific team for an event or year.

get_team_awards

Return awards earned by a team in a given year.

get_team_media

Obtain media related to a team, such as photos and videos.

get_event

Get comprehensive details about a specific event.

get_events

Query multiple events by year or criteria.

get_event_teams

List all teams participating in a particular event.

get_event_rankings

Retrieve rankings for an event.

get_event_matches

Fetch matches for an event.

get_event_oprs

Get offensive, defensive, and other performance ratings for an event.

get_match

Retrieve detailed information about a specific match, including alliances and scores.

get_match_simple

Get a simplified view of a match with core details.

get_match_zebra

Obtain robot tracking data for a match, if available.

get_districts

List districts and basic information.

get_district_rankings

Rankings within a district.

get_district_events

Events within a district.

get_district_teams

Teams participating in district events.

get_teams

Paginated list of teams.

get_teams_by_year

Teams active in a specific year.

get_status

API status and health information.