Kia Access MCP

A Model Context Protocol 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 confirm-gated door, climate, and charging commands.

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 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.

Installation

1. Clone and build

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

2. Configure credentials

cp .env.example .env
# Edit .env: KIA_USERNAME, KIA_PASSWORD (and optionally KIA_WRITE_MODE)

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

3. Register with Claude Code

{
  "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 (needs confirm: true) — 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 with confirm: true and repeat from step 2.

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.

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:

• Confirm-gated. Without confirm: true there is no network call at all, just a preview of the exact request that would be sent.
• 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.

Tools

Account and session

Reads

Commands

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.

Hosted connector

The same tools can run as a Cloudflare Worker for use as a remote connector on claude.ai. Sign in with your Kia email and password on the connector's own login page: submit once to have Kia text you a code, then submit again with the code. The connector completes the verification itself and keeps the resulting remember-me token in your encrypted credentials, so it never asks again — you do not need the local server, and you never handle a token. See docs/DEPLOY-CONNECTOR.md.

Development

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
npm run worker:test   # the hosted-connector suite, under the Workers runtime

License

MIT