Provides voice interaction capabilities through OpenAI's API for transcription and text-to-speech functionality, enabling real-time voice communication with racing telemetry data
Race MCP Server
A comprehensive MCP (Model Context Protocol) server for iRacing telemetry data that provides real-time racing advice, car spotting, telemetry analysis, and conversational interaction about racing data.
🏁 Overview
This MCP server transforms iRacing telemetry data into actionable racing insights through:
- Real-time telemetry streaming with advanced analytics
- AI-powered racing coaching based on driving patterns
- Intelligent car spotting and traffic awareness
- Detailed lap analysis with improvement suggestions
- Session monitoring with performance trends
- Conversational interface for natural racing discussions
🚀 Features
Core Capabilities
- Live Telemetry Processing: Real-time data from iRacing via pyirsdk
- Advanced Analytics: G-force calculations, racing line analysis, gear optimization
- Racing AI Coach: Personalized advice based on driving style and situation
- Car Spotting System: Traffic awareness and positioning intelligence
- Performance Analysis: Lap-by-lap breakdown with improvement suggestions
- Session Tracking: Long-term performance trends and statistics
MCP Integration
- 5 Interactive Tools: Direct telemetry access and analysis functions
- 3 Live Resources: Streaming data feeds for continuous monitoring
- 3 AI Prompts: Specialized coaching personalities (coach, spotter, setup analyst)
- JSON-RPC 2.0: Standard MCP protocol compliance
- STDIO Transport: Ready for integration with MCP clients
📦 Installation
Prerequisites
- Python 3.8+
- iRacing simulator (for live telemetry)
- Virtual environment (recommended)
Quick Setup
Manual Dependencies
If you prefer manual installation:
🎮 Usage
Running the Server
Mock iRacing Data Generator
For development without the simulator, a standalone process can emit realistic iRacing-style telemetry over TCP.
Clients can connect to the specified host and port to receive newline-delimited JSON telemetry frames that mimic the structure of a real iRacing stream.
Launching with a GUI
After installation, you can start the server using a small GUI:
The GUI offers start/stop controls and displays server logs for quick race prep.
Testing the Server
🎙 Voice Interaction
Real-time voice communication is supported through optional audio utilities.
Prerequisites
- OpenAI API key set in
OPENAI_API_KEY
- Install voice dependencies:
pip install race-mcp-server[voice]
Example Usage
This records a short microphone clip, sends it to OpenAI for transcription and speaks the model's response back to the user.
🛠 Available Tools
1. get_telemetry
Purpose: Retrieve current telemetry data with enhanced analytics
Returns: Complete telemetry data including speed, RPM, position, G-forces, and racing line analysis
2. spot_cars
Purpose: Identify and analyze nearby cars for situational awareness
Returns: List of nearby cars with relative positions, speeds, and trajectory predictions
3. get_racing_advice
Purpose: Get AI-powered coaching advice based on current situation
Returns: Personalized advice with priority levels and specific recommendations
4. analyze_lap
Purpose: Detailed analysis of lap performance with improvement suggestions
Returns: Sector times, racing line efficiency, consistency ratings, and specific improvement areas
5. track_session
Purpose: Monitor overall session progress and performance trends
Returns: Session statistics, pace trends, fuel usage, and tire degradation analysis
📊 Live Resources
1. telemetry://live-stream
Continuous telemetry data stream with real-time updates
2. session://current-info
Current session information including track, conditions, and session type
3. track://layout-info
Track-specific information including turn locations and racing line data
🤖 AI Prompts
1. racing_coach
Personality: Professional racing instructor Focus: Technique improvement and strategic advice Use Case: General racing improvement and learning
2. car_spotter
Personality: Experienced spotter focused on safety and positioning
Focus: Traffic management and situational awareness
Use Case: Race situations and traffic navigation
3. setup_analyst
Personality: Technical setup engineer Focus: Vehicle setup optimization and handling analysis Use Case: Car setup tuning and technical adjustments
🧪 Testing
Run the Test Client
The test client provides a comprehensive way to interact with all server functionality:
Test Client Features
- Tool Testing: Tests all 5 MCP tools with realistic parameters
- Resource Access: Validates all 3 live resources
- Prompt Testing: Exercises all 3 AI coaching prompts
- Error Handling: Tests server resilience and error responses
- Performance: Shows response times and data validation
Manual Server Testing
🔧 Configuration
Environment Variables
Server Configuration
Modify settings in src/race_mcp_server/main.py
:
- Telemetry update intervals
- Simulation mode parameters
- Logging levels
- Analysis parameters
Startup Script Options
🔍 Troubleshooting
Common Issues
- "pyirsdk connection failed"
- Ensure iRacing is running and in a session
- Check that iRacing telemetry output is enabled
- The server will run in simulation mode if iRacing isn't available
- "Tool execution failed"
- Check server logs for detailed error messages
- Verify the tool arguments match the expected schema
- Try restarting the server
- "Resource access failed"
- Resources return simulated data when iRacing isn't running
- Check that the server started without errors
- Verify the resource URIs are correct
Debug Mode
Log Files
- Server logs: Written to console (redirect to file if needed)
- iRacing connection status: Logged at startup
- Tool execution: Logged for each request
🏗 Development
Project Structure
Adding New Features
- New Tools: Add methods to
RaceMCPServer
class inmain.py
- New Resources: Extend the resource handlers
- Enhanced Analytics: Modify
telemetry_processor.py
- New Prompts: Add prompt templates to the prompts section
Testing New Features
Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Submit a pull request with detailed description
📋 Requirements
Core Dependencies
System Requirements
- OS: Windows, macOS, or Linux
- Python: 3.8+ (tested with 3.10.12)
- Memory: 100MB+ available
- iRacing: Any recent version with telemetry enabled (optional - server runs in simulation mode without it)
Optional Dependencies
- pytest: For running extended test suites
- MCP Client: Any MCP-compatible client for integration
📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
🏆 Acknowledgments
- iRacing: For providing the comprehensive telemetry API
- MCP Community: For the excellent Model Context Protocol framework
- Racing Community: For feedback and feature suggestions
Ready to improve your lap times? Start the server and run the test client to see it in action! 🏎️💨
Configuration
The server can be configured via environment variables:
IRACING_TELEMETRY_INTERVAL
- Telemetry update interval in seconds (default: 1.0)RACE_MCP_LOG_LEVEL
- Logging level (default: INFO)RACE_MCP_ENABLE_SPOTTING
- Enable car spotting features (default: true)
Architecture
Development
License
MIT License
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables AI-powered racing coaching and telemetry analysis for iRacing, providing real-time racing advice, car spotting, lap analysis, and conversational interaction with racing data through live telemetry streaming.