@draiv/mcp-server

MCP (Model Context Protocol) server for the DRAIV car rental platform. Search for available cars, manage bookings, and administer the platform through AI assistants like Claude.

Quick Start

Claude Code

Add to .claude/settings.local.json:

{
  "mcpServers": {
    "draiv": {
      "command": "npx",
      "args": ["@draiv/mcp-server"]
    }
  }
}

Claude Desktop

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "draiv": {
      "command": "npx",
      "args": ["@draiv/mcp-server"]
    }
  }
}

That's it — no environment variables needed. The server connects to DRAIV production by default.

Authentication

Without authentication, only public tools (car search, knowledge base) are available. To unlock user, fleet, or admin tools, authenticate via OAuth or API key.

OAuth (Recommended)

npx @draiv/mcp-server auth login

This opens your browser to sign in with your DRAIV account. Credentials are stored locally at ~/.draiv/credentials.json.

npx @draiv/mcp-server auth status   # Check current auth state
npx @draiv/mcp-server auth logout   # Remove stored credentials

API Key (CI/CD)

Set DRAIV_API_KEY as an environment variable in your MCP config:

{
  "mcpServers": {
    "draiv": {
      "command": "npx",
      "args": ["@draiv/mcp-server"],
      "env": {
        "DRAIV_API_KEY": "draiv_sk_live_your_api_key_here"
      }
    }
  }
}

Auth Priority

1. DRAIV_API_KEY env var (takes precedence)
2. OAuth credentials (~/.draiv/credentials.json)
3. Public mode (search-only)

Access Levels

| Role | Level | Description | |------|-------|-------------| | public | 0 | Car search, knowledge base, time — no auth required | | user | 1 | Own bookings and active rental info | | fleetOwner | 2 | Fleet stats, car management, license plate lookup | | admin | 3 | Full platform access — bookings, users, deposits, messaging |

Available Tools

Public (No Auth)

| Tool | Description | |------|-------------| | search_available_cars | Search cars by city, type, seats, price, dates, fuel type, and more | | search_with_alternatives | Smart search with fallback suggestions when no exact matches | | get_next_available_time | Find when a car type becomes available | | knowledge_base_search | Search FAQs, policies, and how-to guides | | get_current_time | Get current server time with pre-calculated timestamps | | get_user_preferences | Get learned preferences for a returning visitor | | get_proactive_suggestions | Personalized welcome message and car suggestions |

User (Requires Auth)

| Tool | Description | |------|-------------| | get_user_bookings | Your booking history | | get_active_booking | Current or upcoming booking with pickup details |

Fleet Owner (Requires Auth)

| Tool | Description | |------|-------------| | get_car_by_license_plate | Look up car details by license plate | | list_owner_cars | List your fleet cars with status filter | | toggle_car_status | Set a car to available or inactive | | get_fleet_stats | Fleet overview: cars, active rentals, earnings |

Admin (Requires Auth)

Car Management

| Tool | Description | |------|-------------| | list_pending_cars | Cars awaiting approval | | approve_car | Approve a pending car listing | | reject_car | Reject a car listing with reason | | get_platform_stats | Platform-wide car counts and health metrics | | get_car_access_logs | Unlock/lock access logs by phone or plate | | get_access_log_stats | Access log summary and success rates |

Booking Management

| Tool | Description | |------|-------------| | list_bookings | List all bookings with status filter | | get_booking_details | Full booking details including payment and insurance | | get_booking_refunds | Deposit and refund history for a booking | | submit_custom_refund | Issue a custom refund (discount, compensation, correction, goodwill) against a booking | | swap_booking_car | Reassign a booking to a different car (accepts booking id or DRAIV-XXXXXX; car id or plate). Moves availability old→new, keeps price, optional confirmation email | | cancel_booking | Cancel a booking | | complete_booking | Mark a booking as completed | | search_bookings | Advanced search by user, status, date, amount, deposits | | get_abandoned_drafts | Draft bookings that were never completed | | get_pending_deposit_reviews | Deposits awaiting admin review | | submit_deposit_review | Approve/retain/partial release a deposit |

User Management

| Tool | Description | |------|-------------| | lookup_user | Find user by email | | list_users | List all platform users | | get_user_bookings_by_email | All bookings for a user | | get_user_activity | Activity timeline: rentals, verifications, events | | get_user_loyalty_status | Loyalty tier, discount, and points | | get_license_status | Driver's license verification status | | update_user_verification | Update user verification status | | manage_user_insurance | Manage user insurance settings | | update_user_name | Update a user's name | | manage_user_role | Assign or change user roles | | get_user_timeline | Unified interaction timeline across all channels | | diagnose_identity_resolution | Test identity resolution for an identifier | | get_pending_agent_drafts | Pending agent actions awaiting approval |

WhatsApp Messaging

| Tool | Description | |------|-------------| | send_whatsapp_message | Send a message to a user | | send_refund_notification | Notify user about a processed refund | | get_message_history | History of admin-sent messages |

Email

| Tool | Description | |------|-------------| | list_received_emails | List received emails | | get_received_email | Get full email content | | list_email_attachments | List attachments for an email | | get_email_attachment | Get a specific email attachment |

Search Filters

The search_available_cars tool supports:

| Filter | Type | Example | |--------|------|---------| | city | string | "Zürich", "Basel" | | make | string | "BMW", "Tesla" | | model | string | "Model 3", "X3" | | bodyType | string | "SUV", "Sedan", "Hatchback" | | seats | number | Minimum seats required | | transmission | string | "automatic" or "manual" | | fuelType | string | "electric", "petrol", "diesel" | | maxDailyRate | number | Max price in CHF/day | | startTime / endTime | number | Unix timestamp (ms) | | is4x4 | boolean | 4x4/AWD vehicles only | | minRange | number | Minimum EV range in km | | features | string[] | ["pet_friendly", "carplay"] |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CONVEX_URL | https://careful-jaguar-818.convex.cloud | Convex deployment URL (override for dev) | | DRAIV_API_KEY | — | API key for authenticated access |

Example Usage

Once configured, use natural language in Claude:

"Search for electric cars in Zürich under 100 CHF per day"

"Are there any SUVs available in Basel this weekend?"

"When is the next Tesla available in Zürich?"

"Show me my current booking"

Rate Limiting

60 requests per 60-second window. When rate limited, wait for the retryAfter seconds in the response.

Changelog

v0.4.0 (February 2026)

• OAuth authentication via browser (auth login/logout/status)
• CONVEX_URL now defaults to production — no env vars needed for setup
• Added admin tools: booking management, user management, deposits, access logs
• Added fleet owner tools: car management, fleet stats
• Added WhatsApp messaging tools
• Added email tools
• Added search_with_alternatives with fallback suggestions
• Added get_next_available_time for availability queries
• Added knowledge base search and personalization tools
• Role-based access control (public → user → fleetOwner → admin)
• Enhanced search filters: is4x4, minRange, features

v0.3.0

• Rate limiting (60 req/min)
• Usage tracking

v0.2.0

• API key authentication
• Role-based access control

v0.1.0

• Initial release with car search

Support

• Website: draiv.ch
• Email: [email protected]
• WhatsApp: +41 77 456 99 07

License

MIT