yangjack8192/vex-mcp-server

VEX MCP Server

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
• 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

🚀 Quick Start (1-Minute Setup!)

Prerequisites

• Node.js 18.0.0 or higher
• A RobotEvents API token (free registration required)

⚡ Method 1: NPM Installation (Recommended)

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"

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

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

• NPM Package: https://www.npmjs.com/package/vex-mcp-server
• Issues: Report bugs at GitHub Issues
• VEX Community: Discuss at VEX Forum
• RobotEvents API: Documentation at https://www.robotevents.com/api/v2

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 file for details.