Race

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

python

1

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "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 .

# 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

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

# 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