Offers PostgreSQL as a storage backend choice for managing car customization data and build persistence in production environments
Provides Redis as an alternative storage backend option for car build data persistence through the pluggable storage architecture
Uses SQLite as the default storage backend for persisting car builds, customizations, and driver profiles with WAL mode for better concurrency
šļø Pimp My Ride MCP Server
A Model Context Protocol (MCP) server for car customization and racing. Build and customize your dream ride with natural language through ChatGPT or Claude!
Note: This project is an homage to the MTV show Pimp My Ride hosted by Xzibit. Not affiliated with or endorsed by MTV.
Features
šØ Car Customization - Colors, wheels, body kits, spoilers, exhausts, decals, and underglow
šļø Driver Profiles - Choose your racing persona (RoadRage, SpeedDemon, CoolCalmCollected, etc.)
š¾ Build Management - Save, load, and manage multiple car builds
š Performance Scoring - Get calculated performance scores for your builds
š Pomerium Authentication - Secure identity-aware access with Pomerium proxy
šļø Pluggable Storage - SQLite by default, extensible to Redis, PostgreSQL, DynamoDB
Security
ā ļø This MCP server has no built-in authentication or authorization. It reads identity from HTTP headers and trusts them implicitly.
For production deployments, secure this server behind , an AI gateway that provides:
š Centralized Authentication - OAuth/OIDC integration with your identity provider
š”ļø Fine-grained Authorization - Policy-based access control at the tool and method level
š Automatic Token Management - Handles OAuth token refresh transparently
š Observability - Detailed logs of AI agent interactions, tool calls, and parameters
š Secure Gateway - Expose internal MCP servers safely to AI agents
Pomerium enables you to define policies like:
Which users can access which tools
Rate limiting per user or group
Audit logging of all tool calls
Dynamic access control based on user attributes
Architecture with Pomerium
Learn more: Pomerium MCP Documentation
Quick Start
Installation
Configuration
Create a .env
file (see .env.example
):
Development
Production
Available Tools
Car Customization
getCurrentBuild
Retrieve or create your active car build with all customizations.
updateCarConfig
Update car attributes:
color - Primary color (red, blue, green, yellow, orange, purple, pink, black, white, silver, gold, cyan, magenta, lime)
secondaryColor - Secondary/accent color
wheels - Wheel type (stock, sport, racing, offroad, chrome, neon, spinner)
bodyKit - Body kit style (stock, sport, racing, drift, luxury, rally, muscle)
decal - Decal/livery (none, racing_stripes, flames, tribal, camo, carbon_fiber, checkered, sponsor, custom)
spoiler - Spoiler type (none, stock, sport, racing, gt_wing, ducktail)
exhaust - Exhaust system (stock, sport, racing, dual, quad, side_exit)
underglow - Underglow lighting (none, red, blue, green, purple, rainbow, white)
performance - Performance stats (power, grip, aero, weight: 0-100)
updateDriverProfile
Set driver persona and nickname:
persona - Driver personality: CoolCalmCollected, RoadRage, SpeedDemon, Cautious, ShowOff, Tactical, Wildcard
nickname - Driver nickname (1-50 characters)
getCustomizationOptions
Get all available customization options for car parts and driver personas.
getPersonaInfo
Get detailed information about driver personas including racing style, strengths, and weaknesses.
Build Management
saveBuild
Save the current car build under a specific name.
loadBuild
Load a saved car build and make it active.
listBuilds
List all saved car builds with pagination support.
deleteBuild
Delete a saved car build (cannot delete active build).
getBuildDetails
Get detailed information about a build including calculated performance score.
Architecture
Storage Layer
The KV storage abstraction provides:
Namespaces - Logical data isolation
TTL Expiration - Automatic cleanup of expired entries
CAS Versioning - Compare-and-Set for concurrent updates
Pagination - Cursor-based pagination for large datasets
Default implementation uses SQLite with WAL mode for better concurrency.
Authentication
Pomerium authentication resolves user identity from HTTP headers:
X-Pomerium-Claim-Sub
- User IDX-Pomerium-Claim-Email
- Email addressX-Pomerium-Claim-Name
- Display nameX-Pomerium-JWT-Assertion
- JWT token (fallback)
In development mode without Pomerium, the server generates anonymous session-based user IDs.
Data Model
Build Structure:
API Endpoints
MCP Protocol
POST /mcp
- MCP tool callsGET /mcp
- Server info
Health Check
GET /health
- Storage health status
Environment Variables
Variable | Description | Default |
| Server host/interface to bind |
|
| Server port |
|
| Environment (development/production/test) |
|
| Logging level (error/warn/info/debug) |
|
| Storage type (sqlite/redis/postgres/dynamodb) |
|
| SQLite database file path |
|
| Enable SQL query logging |
|
Development
Scripts
Project Structure
Deployment
Docker
Available on Docker Hub: nickytonline/pimp-my-ride-mcp
With Pomerium (Recommended for Production)
Deploy behind Pomerium for secure, policy-based access control:
See Pomerium MCP docs for advanced configuration including:
Tool-level authorization
User/group-based access control
Rate limiting
OAuth upstream integration
Roadmap
Phase 2 - AI Assistance
randomizeBuild
- Generate random themed buildssuggestUpgrades
- AI-powered upgrade recommendationsgenerateLivery
- Color scheme suggestions
Phase 3 - Racing
simulateRace
- Race simulationgetLeaderboard
- Global rankingsRace results persistence
License
MIT
Documentation
Product Requirements Document (PRD) - Detailed architecture, data models, and implementation phases
Repository Guidelines (AGENTS.md) - Development conventions, testing, and contribution guidelines
About Pomeranian Kart
Pomeranian Kart is a racing game that uses this MCP server for car customization. Players interact with the game through natural language, building and customizing their dream cars before racing.
References
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables car customization and racing through natural language by building dream rides with colors, wheels, body kits, spoilers, and driver personas. Supports saving multiple builds with performance scoring and secure authentication.