home / mcp / race mcp server

Race MCP Server

My attempt at making an agentic race engineer for sim-racing

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "consolecowboy0-race-mcp": {
      "command": "python",
      "args": [
        "-m",
        "race_mcp_server"
      ],
      "env": {
        "MCP_DEBUG": "1",
        "IRSDK_PATH": "/path/to/irsdk",
        "RACE_MCP_SIMULATION": "1"
      }
    }
  }
}

You run a dedicated MCP server that converts iRacing telemetry into real-time racing insights, coaching, car spotting, and conversational discussions about your racing data. It streams telemetry, provides AI-driven feedback, and helps you monitor performance across sessions with actionable recommendations.

How to use

You connect an MCP client to the server to access live telemetry, coaching prompts, car spotting, and lap analysis. Use the provided tools to request current telemetry, spot nearby cars, generate AI coaching, analyze a lap, and track session trends. The server supports a conversational interface for natural discussions about racing data and integrates with your existing MCP client workflow via standard JSON-RPC 2.0 over STDIO transport.

How to install

# Prerequisites
Python 3.8+
IRacing simulator (for live telemetry)
Virtual environment (recommended)

# Quick Setup
# Clone the repository
git clone <your-repo-url>
cd race-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package with dependencies
pip install -e .
```

```bash
# Manual dependencies
pip install mcp pyirsdk pydantic aiofiles

Configuration and basic usage notes

Configure environment and start the server using the available STDIO commands. You can run the server directly in your environment or use the startup helper scripts. The following commands assume you are in the project root and your virtual environment is active.

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the MCP server directly
python -m race_mcp_server

# Or use the convenient startup script
./start_server.sh

# Run with debug logging
./start_server.sh --debug

# Run in simulation mode (no iRacing required)
./start_server.sh --simulation
```

```bash
# Start the mock telemetry stream for development without iRacing
python -m race_mcp_server.mock_iracing_stream --port 9000
```

```bash
# Start a small GUI for quick race prep
race-mcp-gui

Additional sections

Environment variables you can set to customize behavior include:

# Enable debug logging
export MCP_DEBUG=1

# Force simulation mode
export RACE_MCP_SIMULATION=1

# Set custom iRacing data path (if needed)
export IRSDK_PATH=/path/to/irsdk
```

These variables influence logging, simulation behavior, and where telemetry data is sourced from if iRacing is not available.

Available tools

get_telemetry

Retrieve current telemetry data with enhanced analytics such as speed, RPM, position, G-forces, and racing line analysis

spot_cars

Identify and analyze nearby cars for situational awareness, including distance and trajectory predictions

get_racing_advice

Get AI-powered coaching based on current situation with priority levels and actionable recommendations

analyze_lap

Detailed analysis of lap performance with improvement suggestions, including sector times and line efficiency

track_session

Monitor overall session progress, pace trends, and resource usage