toyota-mcp

<!-- mcp-name: io.github.zepgram/toyota -->

<p align="center">
  <img src="https://raw.githubusercontent.com/zepgram/toyota-mcp/main/docs/toyota-emblem.svg"
       alt="Toyota" width="76">
</p>

<h1 align="center">toyota-mcp — Toyota &amp; Lexus MCP server for Claude and other AI assistants</h1>

<p align="center">
  <a href="https://pypi.org/project/toyota-mcp/"><img src="https://img.shields.io/pypi/v/toyota-mcp" alt="PyPI"></a>
  <a href="https://github.com/zepgram/toyota-mcp/actions/workflows/ci.yml"><img src="https://github.com/zepgram/toyota-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/toyota-mcp/"><img src="https://img.shields.io/pypi/pyversions/toyota-mcp" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

**Ask your Toyota anything.** `toyota-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
(MCP) server that connects a **MyToyota** or **MyLexus** Europe account to Claude,
Claude Code, Cursor, VS Code or any MCP client — read your car's fuel level,
range, location, trips and health, and send remote commands (lock, climate,
charging) in plain language.

> *"How much range is left?"* · *"Where is the car?"* · *"Is it locked?"* ·
> *"What did the last trip consume?"* · *"What's my EV share this month?"* ·
> *"Pre-heat the car for 8 am."* · *"Cheapest petrol near the car?"*

| | |
|---|---|
| **Vehicles** | Toyota and Lexus, **Europe only** (Toyota Connected Services / `ctpa-oneapi`) |
| **Powertrains** | petrol, diesel, full hybrid, plug-in hybrid, electric |
| **Tools** | 13 read + 11 remote commands + 1 prompt ([full list](#available-tools)) |
| **Install** | `uvx toyota-mcp` — no clone, no build |
| **Requires** | a MyToyota/MyLexus account **without MFA**, Python 3.11+ |
| **Built on** | [pytoyoda](https://github.com/pytoyoda/pytoyoda), the community client for Toyota Europe |

## Requirements

- A **MyToyota Europe** account (the API covers Europe only — North America and
  Japan use entirely different systems).
- Sign in with `toyota-mcp login`, or with account credentials in the
  environment (that path cannot handle MFA/2FA).
- The vehicle must appear in the MyToyota mobile app.
- Python 3.11+ and [`uv`](https://docs.astral.sh/uv/) for the zero-install `uvx` launcher
  (`uvx` fetches a suitable Python by itself).

> **Unofficial API.** Toyota can change or break this API at any time without
> notice. All API access is isolated behind pytoyoda, which historically absorbs
> such breakage within days.

## Quickstart

### Sign in once

```bash
uvx toyota-mcp login
```

Your browser opens Toyota's own sign-in page. Toyota then redirects to an
address the browser cannot follow (`com.toyota.oneapp:/…`) and shows an error —
that is expected: copy that address from the address bar and paste it back. The
session is saved in your operating system's credential store and refreshed
automatically. **Your password is never seen by this program and never written
to a configuration file.** `uvx toyota-mcp logout` forgets it.

### Claude Desktop

Add to `claude_desktop_config.json` (macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "toyota": {
      "command": "uvx",
      "args": ["toyota-mcp"]
    }
  }
}
```

Add options after `toyota-mcp` in `args` — for example
`["toyota-mcp", "--addresses", "osm"]` for postal addresses, or
`["toyota-mcp", "--read-only"]` to leave every remote command out.

### Claude Code

```bash
claude mcp add --transport stdio toyota -- uvx toyota-mcp
```

### Cursor, VS Code and other MCP clients

Any client that speaks stdio works with the same shape — command `uvx`,
arguments `["toyota-mcp"]`. In VS Code, add it to `.vscode/mcp.json`; in Cursor,
to `~/.cursor/mcp.json`.

### First contact: the doctor

Before wiring anything into an MCP host, check your setup from a terminal:

```bash
uvx toyota-mcp doctor
```

It validates credentials, lists your vehicles, and prints which tools your
specific car supports. Exit codes: `0` ok · `2` config · `3` auth ·
`4` no vehicle · `5` API error · `6` command rejected (`probe`).

## Remote access — the "Connect" button

By default the server runs on stdio, next to the MCP client. Point it at a URL
instead and it becomes a remote MCP server with its own OAuth 2.1 authorization
server, so a client connects the way it connects to Gmail or GitHub: paste the
URL, press **Connect**, approve in the browser.

```bash
toyota-mcp --http https://toyota.example.com
```

Nothing else to configure — **connecting is signing in to Toyota**:

1. Paste `https://toyota.example.com/mcp` into your client and press Connect.
2. The client registers itself and sends you to this server's sign-in page.
3. Enter the MyToyota email and password, then pick which vehicle to use when
   the account has several.
4. The client gets its token; the server keeps only Toyota's refresh token.

Signing in to the Toyota account *is* the proof that you own the deployment —
there is no shared code and no user database. A server already connected to one
account refuses a sign-in with a different one.

Toyota's own web login ends on a mobile deep link (`com.toyota.oneapp:/…`) that
a browser cannot follow — on a phone it opens the MyToyota app instead — so the
credentials are posted to Toyota by the server you run. They are never written
down: only the refresh token Toyota returns is kept. Accounts with two-factor
authentication cannot be used, as Toyota's vehicle API does not support them.

Run it on a machine of yours (a home server, a Raspberry Pi), behind a
TLS-terminating proxy: the server refuses a non-`https://` public URL other
than localhost, because bearer tokens must not travel in clear. Registered
clients and issued tokens are kept in `~/.local/state/toyota-mcp/oauth.json`
(mode 600) so a restart does not disconnect anyone; access tokens last an hour
and refresh silently.

### With Docker

```bash
docker build -t toyota-mcp --build-arg VERSION=0.3.0 .
docker run -d --name toyota-mcp -v toyota-mcp:/data -p 127.0.0.1:8787:8787 \
  toyota-mcp --http https://toyota.example.com --host 0.0.0.0
```

A container has no credential store, so the session and the grants live in
`/data` — keep it as a volume or signing in again is the price of a restart.
`TOYOTA_SESSION_FILE` moves the session file elsewhere.

## Authentication

Nothing has to be configured before the first use. A server with no account
connected still starts and says what to do: over HTTP the Connect flow signs you
in, otherwise `toyota-mcp login` does. `toyota_list_vehicles` and
`toyota_select_vehicle` then choose the car from the conversation.

Toyota has no third-party API programme: there is no developer portal, no
per-application token, and the mobile app signs in with your account password.
This server therefore offers two ways in, and prefers the one where it never
holds that password.

**`toyota-mcp login`.** Asks for the MyToyota email and password, signs in to
Toyota, and keeps only the **refresh token** — in your operating system's
credential store (Keychain, Windows Credential Locker, Secret Service), or in a
file when there is none. The password is never written down, and never lands in
an MCP host's configuration file.

**Password in the environment.** `TOYOTA_USERNAME` and `TOYOTA_PASSWORD` still
work for unattended setups, but most MCP hosts store their `env` block as plain
text on disk, so prefer `toyota-mcp login`.

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `TOYOTA_USERNAME` | no | — | MyToyota account email — only for the password sign-in |
| `TOYOTA_PASSWORD` | no | — | MyToyota account password — only for the password sign-in |
| `TOYOTA_VIN` | no | — | Pins one vehicle, overriding the choice made at sign-in |
| `TOYOTA_BRAND` | no | `T` | `T` Toyota, `L` Lexus |
| `TOYOTA_USE_METRIC` | no | `true` | `false` switches to miles/gallons |

Features are command-line options, visible in `toyota-mcp --help` and in your
host's `args`:

| Option | Default | Description |
|---|---|---|
| `--read-only` | off | register only the read tools — no lock, trunk, lights, climate or charging commands |
| `--addresses osm\|fr` | off | turn coordinates into addresses: `osm` worldwide (OpenStreetMap), `fr` France (also enables fuel prices). Off by default because it sends the car's position to that service |
| `--places SPEC` | — | named places, `"home=43.6045,1.4440;work=43.6290,1.3630"`: positions within 200 m are labelled |

```json
"toyota": {
  "command": "uvx",
  "args": ["toyota-mcp", "--addresses", "osm", "--places", "home=43.6045,1.4440"]
}
```

A local `.env` file works too (see `.env.example`). Credentials never touch disk
otherwise; tokens live in memory only.

<a id="available-tools"></a>

## Available tools

Read tools are `readOnlyHint: true`. The remote commands below are registered
unless the server runs with `--read-only`.

| Tool | Example question | Key fields |
|---|---|---|
| `toyota_list_vehicles` / `toyota_select_vehicle` | *Which cars? Use the Yaris.* | every vehicle on the account, and which one the tools act on |
| `toyota_get_vehicle_info` | *What car is this? Is the subscription active?* | model, year, plate, colour, first use, subscriptions, declared remote capabilities |
| `toyota_get_energy` | *How much range is left?* | fuel %, range (km/mi), battery or an explicit "not applicable" note |
| `toyota_get_charging` | *Is it charging? When is the next scheduled charge?* | plug-in battery %, charging status, EV range, time to full, schedules (PHEV / EV only) |
| `toyota_get_status` | *Is the car locked? Did I leave the lights on?* | doors/windows/trunk/hood, lock state, lights, rear-seat reminder, overall status |
| `toyota_get_location` | *Where is the car?* | lat/lon, address (with open data), Google Maps link |
| `toyota_get_odometer` | *How many km on the