# Tesla Robotaxi MCP

An unofficial local [Model Context Protocol](https://modelcontextprotocol.io/)
server for Tesla Robotaxi rider accounts.

It gives an agent eight tools:

- Search Robotaxi places
- Get live fare and route previews
- List saved Robotaxi payment methods
- Book a quoted ride
- Read live ride and vehicle status
- Preview and confirm cancellation
- Get ride history

> [!WARNING]
> This project uses Tesla's private, reverse-engineered Robotaxi rider APIs. It
> is not affiliated with or endorsed by Tesla. The protocol can change without
> notice. Use it only with your own account and review Tesla's terms.

## Requirements

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
- A Tesla account with Robotaxi access

The server runs locally over stdio. Credential acquisition stays outside this
package: obtain a Tesla Robotaxi refresh token from your own signed-in app
session (for example via a local Charles capture of
`POST auth.tesla.com/oauth2/v3/token`), then store only that token.

## 1. Configure credentials

The server checks, in order:

1. `ROBOTAXI_REFRESH_TOKEN` and optional `ROBOTAXI_AREA_NAME`
2. `ROBOTAXI_CREDENTIALS_FILE`
3. `~/.config/robotaxi/credentials.json`

The default credential file has this shape:

```json
{
  "refresh_token": "your-token",
  "area_name": "1:bay-area"
}
```

Create it locally with file mode `0600`. Never commit a capture, token, or
credential file.

The optional keys `device_public_key` and `device_attestation` (base64
protobuf) support accounts for which Tesla enforces the app's device
attestation fields during booking. Read-only tools do not need them.

## 2. Add the MCP server

Add this to `~/.cursor/mcp.json` or a project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "robotaxi": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nathanielangafor/robotaxi-mcp",
        "robotaxi-mcp"
      ]
    }
  }
}
```

Restart or reload MCP servers in the client.

## Safe agent behavior

- Resolve ambiguous places before quoting.
- Check status and list payment methods before requesting a fresh quote.
- Show the canonical pickup, dropoff, and fare.
- Only pass `confirmation: "BOOK"` after the user explicitly asks to book.
- Call `robotaxi_preview_cancellation` and show its result before cancellation.
- Only pass `confirmation: "CANCEL"` after explicit confirmation.
- Never retry a booking or cancellation after `OUTCOME_UNKNOWN`; check status.
- Do not print OAuth tokens, payment-selection blobs, or raw TripX payloads.

The server reinforces this flow with MCP annotations, literal confirmation
arguments, short in-memory proposal/preview caches, and mutation outcome
checks.

## Protocol coverage

The implementation is based on complete Robotaxi 26.8.0 iOS captures:

- Tesla OAuth PKCE with `client_id=rides`
- TripX WebSocket `session_info`, `search_suggestions`,
  `trip_preview_request`, `ride_update`, and `session_summary`
- The structural booking request and UUID + empty-field-4 cancellation request
- Ownership ride history and signed wallet-token endpoints
- Payment `paymentOptions` wallet listing

TripX currently exposes only the Bay Area identifier used by these captures.
Quote, booking, and cancellation are mutation-prone private operations; verify
them after Tesla app releases. A cancellation fee was not present in captured
previews, so the MCP reports it as unavailable rather than guessing.

## Development

```bash
git clone https://github.com/nathanielangafor/robotaxi-mcp
cd robotaxi-mcp
uv sync --extra dev
uv run pytest
uv run robotaxi-mcp
```

Captured sessions and live credentials are intentionally excluded. See
[SECURITY.md](SECURITY.md).