# Kia Access MCP

[![CI](https://github.com/chrischall/kiaaccess-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/kiaaccess-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/kiaaccess-mcp)](https://www.npmjs.com/package/kiaaccess-mcp)
[![license](https://img.shields.io/npm/l/kiaaccess-mcp)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) server that connects Claude to your own Kia vehicle through the Kia Owners API the Kia Access mobile app uses: vehicle status, location, odometer, EV charge state, and confirmation-gated door, climate, and charging commands.

> [!WARNING]
> **AI-developed project.** This codebase was built and is maintained by [Claude Code](https://www.anthropic.com/claude). No human has audited the implementation. Review the code and the tool permissions before pointing it at a real car.

> [!CAUTION]
> **This server can move a two-tonne object and can unlock your car.** Every command tool asks you to confirm before it acts — with a confirmation prompt where the client supports one, otherwise a preview plus a one-time token that only a repeat call can use (see [Confirmations](#confirmations)) — and door lock/unlock is not even registered unless you opt in with `KIA_WRITE_MODE=all`. Read [Vehicle commands](#vehicle-commands) before changing that.

## What you can do

Ask Claude things like:

- *"Is the EV9 locked, and what's the charge at?"*
- *"Warm the car up to 72 for ten minutes"*
- *"Where did I leave the car?"*
- *"Refresh the car's status, then tell me the odometer"*

## Requirements

- [Node.js](https://nodejs.org) 22.5 or later
- A Kia Owners / Kia Access account with an enrolled vehicle, and its password
- A phone or mailbox you can read once, for the one-time MFA passcode

## Acknowledgement of terms

By using this server you accept that:

1. **It uses your own Kia account credentials** to talk to the same private API the Kia Access app uses. It cannot reach anyone else's vehicle or account.
2. **Kia's terms govern your use of it**, exactly as they govern your use of the app. This is not an official or supported integration and is not affiliated with, endorsed by, or sponsored by Kia.
3. **Commands act on a real vehicle in the physical world.** Unlocking leaves the car unsecured until someone locks it; climate preconditioning runs the HVAC and draws power. You are responsible for every command you confirm.
4. **Failed logins have a permanent cost.** Kia counts them (`loginAttempt`) and eventually sets `enforceRecaptcha`, after which server-side login for that account is impossible. This server therefore never retries a rejected credential — see [If login fails](#if-login-fails).

## Installation

### 1. Clone and build

```bash
git clone https://github.com/chrischall/kiaaccess-mcp.git
cd kiaaccess-mcp
npm install
npm run build
```

### 2. Configure credentials

```bash
cp .env.example .env
# Edit .env: KIA_USERNAME, KIA_PASSWORD (and optionally KIA_WRITE_MODE,
#            KIA_DEVICE_ID, KIA_RMTOKEN — see .env.example)
```

`.env` is gitignored. The server never logs credentials, and no tool ever returns your password.

### 3. Register with Claude Code

```json
{
  "mcpServers": {
    "kiaaccess": {
      "command": "npx",
      "args": ["-y", "kiaaccess-mcp"],
      "env": {
        "KIA_USERNAME": "you@example.com",
        "KIA_PASSWORD": "your-password",
        "KIA_WRITE_MODE": "comfort"
      }
    }
  }
}
```

Missing credentials do not stop the server from booting — it starts, answers `tools/list`, and only reports the configuration error when a tool actually needs to call Kia. Run `kia_session_status` to see what it thinks it has.

## The one-time MFA bootstrap

Kia challenges every new device with a one-time passcode. This server bootstraps **once**, stores the resulting remember-me token (`rmtoken`) under `~/.kiaaccess-mcp/session.json`, and from then on mints fresh sessions silently — Kia does not rotate the token and does not challenge again.

Run it through Claude, in this order:

1. **`kia_session_status`** — confirms credentials are present. If it reports `hasSession: false`, continue.
2. **`kia_start_login`** (asks you to confirm first) — sends your credentials, returns an `otpKey` and an `xid`, plus the masked phone/email Kia has on file.
3. **`kia_send_otp`** — pick `SMS` or `EMAIL`. The passcode expires in about two minutes.
4. **`kia_verify_otp`** — hand it the passcode. The token is stored locally and is deliberately **not** returned.
5. **`kia_list_vehicles`** — confirms the session works and gives you the `vehicleKey` every other tool takes.

To start over (revoked token, changed password, handing the machine on), run **`kia_forget_session`** (asks you to confirm first) and repeat from step 2.

### Running it somewhere with no phone to read

The bootstrap needs a human once. A deployment that has no one to read an OTP — a remote host — cannot run it at all, so bootstrap on a machine that can and move the token:

1. Set `KIA_DEVICE_ID` to a fixed uuid **before** the bootstrap, on both machines. The `rmtoken` is minted against a device uuid and is worthless with a different one, and `kia_session_status` only ever reports a truncated prefix — so if you let it be generated, you cannot read back the value you need.
2. Bootstrap as above, then run `kia_export_refresh_token` and confirm it.
3. Give the remote deployment that value as `KIA_RMTOKEN`, alongside `KIA_USERNAME`, `KIA_PASSWORD` and the same `KIA_DEVICE_ID`.

`KIA_RMTOKEN` takes precedence over anything in the local session store, so the deployment's session is whatever you handed it rather than whatever it last wrote. Treat the value like the password it stands in for: it bypasses MFA, and with the account password it grants full control of the vehicle.

### If login fails

Do not retry. Kia increments `loginAttempt` on every rejection and eventually sets `enforceRecaptcha`, which breaks server-side login for that account permanently. Verify the email and password in the Kia Access app first, fix `.env`, restart, and only then try again.

## Vehicle commands

`KIA_WRITE_MODE` decides which command tools are **registered at all**. This is a structural gate, not a runtime check: a tool that was never registered cannot be invoked by any host permission setting or by an instruction injected into the conversation.

| `KIA_WRITE_MODE` | Registers |
|---|---|
| `none` | Nothing but the read tools and the account tools |
| `comfort` *(default)* | Climate start/stop and the charging commands |
| `all` | Also `kia_lock_doors` and `kia_unlock_doors` |

An unrecognised value **fails closed to `none`** and warns on stderr — a typo must never silently grant the ability to unlock a car.

Two more rules hold for every command:

- **Confirmation-gated.** Nothing is sent until you confirm. The confirmation shows the exact request that would be sent; until then there is no network call at all. See [Confirmations](#confirmations).
- **Accepted is not confirmed.** Kia answering "success" only means the request was accepted. The only proof a command took effect is re-reading the vehicle and diffing the field, so results report `commandAccepted` and `stateConfirmed` separately. Observed changes took 30–60 seconds.

## Confirmations

Every write tool (the commands above, plus `kia_start_login`, `kia_forget_session` and `kia_export_refresh_token`) asks you to confirm before it acts. A client that can show a confirmation prompt (Claude Code) shows one, with the exact request. A client that cannot (claude.ai, Claude Desktop) gets a two-step flow instead: the first call does nothing and returns a preview plus a `confirmToken`, and only a repeat call carrying that token proceeds. The token is bound to the exact request previewed — change an argument and it is refused (`DRAFT_CHANGED`) with a fresh preview; use it twice and the second call is refused (`TOKEN_REUSED`).

| variable | default | |
|---|---|---|
| `MCP_CONFIRM_MODE` | `ask-user` | What a write does on a client that cannot show a confirmation prompt (claude.ai, Claude Desktop). `ask-user`: two steps — the first call does nothing and returns a preview plus a token, and the model must get your approval in chat before calling again with it. `auto`: the same two steps, but the model may use the token after reviewing the preview itself. `refuse`: writes are refused on such clients. A client that can show prompts (Claude Code) always gets the real prompt. An unrecognised value is treated as `refuse`. |
| `MCP_CONFIRM_TTL_SECONDS` | `600` | How long a token stays valid. |
| `MCP_CONFIRM_SECRET` | random per process | Signing key; set it only if tokens must survive a server restart. |

## Tools

### Account and session

| Tool | Notes |
|---|---|
| `kia_session_status` | Configured? Bootstrapped? Which write mode? No network call, no secrets — the email is masked and the device id truncated. |
| `kia_start_login` | Step 1 of the MFA bootstrap. Confirmation-gated, because a rejection has a permanent cost. |
| `kia_send_otp` | Step 2 — delivers the passcode by `SMS` or `EMAIL`. |
| `kia_verify_otp` | Step 3 — exchanges the passcode for a stored session. Returns no secret. |
| `kia_forget_session` | Discards the stored token so the bootstrap can be re-run. Local only; confirmation-gated. |
| `kia_export_refresh_token` | Returns the `rmtoken` **in plaintext** — a full MFA bypass. Exists only to move a locally-bootstrapped session into a deployment that cannot run the bootstrap itself, via `KIA_RMTOKEN`. Confirmation-gated. |

### Reads

| Tool | Notes |
|---|---|
| `kia_list_vehicles` | Every enrolled vehicle with its `vehicleKey`, nickname, model, mileage. VINs are masked to the last 6 characters. |
| `kia_vehicle_status` | Cached status: door lock, ignition (`ign3` — on an EV `engine` stays false), the nested `climate` block, and more with `include_raw`. Fast, but only as fresh as the last upload. |
| `kia_refresh_status` | Wakes the telematics unit for a fresh reading. Slower, draws a little power, and returns no data itself — read `kia_vehicle_status` afterwards. |
| `kia_vehicle_location` | Last reported position plus a map link. Not a live GPS fix. |
| `kia_charge_targets` | Target state of charge per plug type. |

### Commands

| Tool | Mode | Notes |
|---|---|---|
| `kia_start_climate` | `comfort` | Preconditioning. Temperature is best-effort: the car may report its own last-set target instead of the one requested. |
| `kia_stop_climate` | `comfort` | Verified by re-reading `climate.airCtrl`. |
| `kia_start_charge` | `comfort` | Verified. Needs the car plugged in — unplugged, Kia accepts the request and nothing happens. Confirm via `evStatus.batteryCharge`. |
| `kia_stop_charge` | `comfort` | Verified. Confirm via `evStatus.batteryCharge`. |
| `kia_set_charge_limits` | `comfort` | Verified, and re-read against `evc/gts` afterwards. Send both plug types — the list replaces the stored one. |
| `kia_lock_doors` | `all` | Verified by re-reading `doorLock`. |
| `kia_unlock_doors` | `all` | Leaves the car physically unsecured. Only run it when the user explicitly asked. |

Every endpoint here was verified live against a 2024 EV9 — the reads and the four door/climate commands on 2026-07-27, and the three `evc/*` charging commands on 2026-07-28 against a plugged-in car. Each was proven by re-reading state, never by the success status: Kia answers `statusCode: 0` the moment it accepts a command, seconds before the car acts, and on an unplugged car it answers success and does nothing at all. Every command result therefore reports "accepted" and "confirmed" separately. The full protocol write-up is in [`docs/KIA-API.md`](docs/KIA-API.md).

## Development

```bash
npm test              # unit tests (no network — fetch is mocked throughout)
npm run test:coverage # the same, with the enforced 100% thresholds
npm run build         # tsc + esbuild bundle
```

## License

[MIT](LICENSE)