Skip to main content
Glama
vex-mcp-server

vex-mcp-server

by yangjack8192

VEX MCP Server

NPM Version NPM Downloads License: MIT Node.js Version VEX Robotics

A Model Context Protocol (MCP) server for VEX Robotics Competition data using the RobotEvents API. This server enables Claude Desktop (and other MCP clients) to access comprehensive VEX competition data including teams, events, rankings, and skills scores.

Features

  • search-teams: Search for VEX teams by number, name, organization, or location

  • get-team-info: Get detailed information about a specific team

  • get-team-awards: Get all awards won by a specific team throughout their competitive history

  • search-events: Search for VEX events by name, date, season, or program level

  • get-event-details: Get detailed information about a specific event

  • get-event-awards: Get award information for VEX events including winners and details

  • get-team-rankings: Get team rankings and performance at events

  • get-skills-scores: Get robot skills scores for teams

  • search-forum: Search the VEX Forum for topics and posts

  • get-forum-topic: Get detailed information about a forum topic with posts

  • get-forum-post: Retrieve a single forum post by ID

  • get-forum-user: Get user profile information from the forum

  • list-forum-categories: List all available forum categories

  • get-latest-forum-topics: Get the latest topics from the forum

  • analyze-match-opponents: Analyze teammates and opponents for all matches at an event, showing their recent award history

Related MCP server: CTFtime MCP Server

🚀 Quick Start (1-Minute Setup!)

Prerequisites

  • Node.js 18.0.0 or higher

  • A RobotEvents API token (free registration required)

One-line installation:

npm install -g vex-mcp-server

Get your RobotEvents API token:

  1. Visit https://www.robotevents.com/api/v2

  2. Click "Request API Access" and fill out the form

  3. Once approved, copy your JWT token

That's it! 🎉 You can now use vex-mcp-server directly in Claude Desktop.

🛠️ Method 2: Development Installation

For developers who want to modify the code:

  1. Clone the repository:

    git clone https://github.com/yangjack8192/vex-mcp-server.git
    cd vex-mcp-server
  2. Install and build:

    npm install
    npm run build

Usage with Claude Desktop

🎯 Super Simple Configuration (NPM Installation)

Location of config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration (NPM version):

{
  "mcpServers": {
    "vex-robotics": {
      "command": "vex-mcp-server",
      "env": {
        "ROBOTEVENTS_TOKEN": "your-actual-jwt-token-here"
      }
    }
  }
}

🛠️ Development Configuration

Configuration (Development version):

{
  "mcpServers": {
    "vex-robotics": {
      "command": "node",
      "args": ["/absolute/path/to/vex-mcp-server/build/index.js"],
      "env": {
        "ROBOTEVENTS_TOKEN": "your-actual-jwt-token-here"
      }
    }
  }
}

📝 Setup Notes:

  • Replace your-actual-jwt-token-here with your real RobotEvents API token

  • Restart Claude Desktop after making configuration changes

  • NPM installation = No paths needed! 🎉

Using the Server

Once configured, you can ask Claude questions like:

  • "Find VEX teams in California"

  • "Search for robotics events in Texas this season"

  • "Get rankings for team 12345 at their last event"

  • "Show me the skills scores for teams at the World Championship"

  • "Analyze all my matches at event 12345 to see who my opponents are"

  • "Help me scout my upcoming matches - show me opponent awards for team 10085A at event RE-VRC-24-1234"

Supported Programs

  • VRC: VEX Robotics Competition (High School)

  • VIQC: VEX IQ Challenge (Elementary/Middle School)

  • VEXU: VEX U (College)

⚠️ Breaking Changes in v2.0.0

Important: If you're upgrading from v1.x, please note these breaking changes:

  • Removed region parameter from search-events tool (due to format inconsistencies)

  • Removed program parameter from search-events tool (not supported by API)

Migration: Update your queries to use alternative parameters like name, level, or season for event filtering.

API Tools Reference

Tool

Description

Parameters

search-teams

Find teams by number, name, or organization

number, name, organization, program, grade, country

get-team-info

Get detailed team information

team_id or team_number (required)

get-team-awards

Get all awards won by a team

team_id or team_number (required), season, event

search-events

Find events by name, date, or level

name, start, end, season, level, eventTypes

get-event-details

Get detailed event information

event_id (required)

get-event-awards

Get award information for events

event_id (required), team, winner

get-team-rankings

Get team rankings at events

team_id, event_id, season

get-skills-scores

Get robot skills scores

team_id, event_id, season

search-forum

Search VEX Forum for topics and posts

query, category, user, order, before, after, max_results

get-forum-topic

Get a forum topic with posts

topic_id, max_posts, include_raw

get-forum-post

Get a single forum post

post_id

get-forum-user

Get forum user profile

username

list-forum-categories

List all forum categories

None

get-latest-forum-topics

Get latest forum topics

category_slug, category_id, page, max_results

analyze-match-opponents

Analyze match opponents and teammates with their award history

team_id or team_number, event_id or event_sku

Match Analysis Tool Details

The analyze-match-opponents tool helps you scout and prepare for competition matches by showing you the award history of your teammates and opponents.

Use Case

Perfect for pre-competition preparation:

  1. Look up all your scheduled matches at an upcoming event

  2. See which teams you'll be paired with and against

  3. Review each team's recent award history

  4. Plan strategy based on opponent competitive background

Parameters

  • team_id or team_number: Your team (either ID like 123456 or number like "10085A")

  • event_id or event_sku: The event to analyze (either ID like 54321 or SKU like "RE-VRC-24-1234")

What You Get

For each match, the tool shows:

  • Match information: Name and scheduled time

  • Your Alliance: Your teammate teams and their recent awards

  • Opponent Alliance: Opposing teams and their recent awards

Awards are displayed with event context (e.g., "Excellence Award (World Championship, VRC 2024-2025)") to give you a complete picture of each team's competitive history.

Example Usage

User: "Analyze my matches for team 10085A at event 54321"

Returns:
- List of all matches
- For each match:
  - Teammate teams with their recent awards
  - Opponent teams with their recent awards
  - Award details including event name and season

Example Output

## Match Q1
Time: 2024-03-15 10:30:00

### Your Alliance (10085A)
**Teammates**:
- 12345B Team Rocket
  - Recent awards: Excellence Award (State Championship, VRC 2024-2025); Tournament Champions (Regional Qualifier, VRC 2024-2025)

### Opponent Alliance
- 99999C Blue Devils
  - Recent awards: Design Award (Signature Event, VRC 2024-2025); Robot Skills Champion (State Championship, VRC 2023-2024)
- 88888D Green Machine
  - No recent awards found

Troubleshooting

Common Issues

"Error: Cannot find module" or "Command failed"

  • Ensure you've run npm run build after installation

  • Check that the path in Claude Desktop config points to the correct build/index.js file

"Authentication failed" or "Invalid token"

  • Verify your RobotEvents API token is correct and active

  • Make sure the token is properly set in environment variables or .env file

  • Check that your API access has been approved by RobotEvents

"No events found" or "Search failed"

  • The server uses a hybrid search approach (web search + API)

  • Some searches may take a few seconds to complete

  • Try different search terms or be more specific

Claude Desktop not recognizing the server

  • Restart Claude Desktop after configuration changes

  • Check the JSON syntax in your configuration file

  • Ensure the file path uses forward slashes, even on Windows

Debug Mode

To see detailed debug logs:

node build/index.js 2>&1 | grep DEBUG

Support

Updates

NPM users (recommended):

npm update -g vex-mcp-server

Development users:

git pull origin main
npm run build

Contributing

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Test your changes thoroughly

  4. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

15 tools
analyze-match-opponentsA

Analyze teammates and opponents for all matches of a team at an event. Shows each team's recent award history to help understand their competitive background. Useful for pre-competition scouting and match preparation.

Inputs: team_id, event_id, event_sku, team_number.

get-event-awardsA

Get awards information for a specific VEX event including team winners, individual winners, and award details

Inputs: event_id (required), team, winner.

get-event-detailsA

Get detailed information about a specific VEX event by event ID or SKU code

Inputs: sku, event_id.

get-forum-postA

Get a single VEX Forum post by its ID

Inputs: post_id (required).

get-forum-topicB

Get a VEX Forum topic by ID, including the topic details and posts/replies

Inputs: topic_id (required), max_posts, include_raw.

get-forum-userA

Get a VEX Forum user's profile information by username

Inputs: username (required).

get-latest-forum-topicsB

Get the latest topics from the VEX Forum, optionally filtered by category

Inputs: page, category_id, max_results, category_slug.

get-skills-scoresA

Get skills scores for VEX teams, either for a specific event or a team's skills history

Inputs: type, season, team_id, event_id.

get-team-awardsB

Get all awards won by a specific VEX team throughout their competitive history. Shows award titles, events, and seasons.

Inputs: event, season, team_id, team_number.

get-team-infoC

Get detailed information about a specific VEX team by team ID or team number

Inputs: team_id, team_number.

get-team-rankingsA

Get ranking information for VEX teams, either for a specific event or a team's historical rankings

Inputs: season, team_id, event_id.

list-forum-categoriesA

List all categories available on the VEX Forum

Inputs: no named parameters.

search-eventsC

Search for VEX robotics events by various criteria like name, season, program, level, or date range

Inputs: end, sku, name, level, +3 more.

search-forumA

Search the VEX Forum (vexforum.com) for topics and posts about VEX robotics. Supports filtering by category, user, date, and sorting options.

Inputs: query (required), user, after, order, +3 more.

search-teamsB

Search for VEX teams by various criteria like team number, event participation, country, program, or grade level

Inputs: event, grade, number, country, +4 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, from team and event searches to forum post retrieval and match analysis. No two tools have overlapping purposes, and even the closely related awards tools are clearly separated by team vs. event context.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (e.g., search-teams, get-team-info, list-forum-categories, analyze-match-opponents). The pattern is predictable and easy to navigate.

    Tool Count5/5

    With 15 tools, this server sits at the upper boundary of the ideal range but each tool covers a distinct need within VEX scouting and forum browsing. The count feels well-scoped for the breadth of data exposed.

    Completeness5/5

    The tool surface covers the full lifecycle for VEX data consumption: team search/details/awards/rankings/skills, event search/details/awards, and forum search/topic/post/user/category access. The added match-opponent analysis fills a key scouting gap, leaving no obvious dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with the Wisembly API to fetch and manage event data, including event details, participants, organizers, and locations.
      2
      1
      ISC
    • F
      license
      A
      quality
      D
      maintenance
      Provides programmatic access to CTFtime.org data for retrieving information about CTF competitions, team rankings, and event results. It enables users to search for upcoming events, analyze team performance, and access historical competition data through a standardized interface.
      9
      4
      -
    • F
      license
      C
      quality
      B
      maintenance
      Enables managing events, organizations, venues, ticket classes, attendees, and orders through the Eventbrite API v3, including creating drafts, publishing or unpublishing events, tracking capacity and sold ticket counts, checking in attendees, and reviewing payouts and transfers.
      87
      1
      -