Skip to main content
Glama

Kia Access MCP

CI npm license

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 confirmation-gated door, climate, and charging commands.

WARNING

AI-developed project. This codebase was built and is maintained by Claude Code. 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) — and door lock/unlock is not even registered unless you opt in with KIA_WRITE_MODE=all. Read 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"

Related MCP server: Tesla MCP Server

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,
#            KIA_DEVICE_ID, KIA_RMTOKEN, KIA_REQUEST_TIMEOUT_MS — see .env.example)

.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 (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 (as its vehicle_key argument).

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 copy the rmtoken value out of ~/.kiaaccess-mcp/session.json yourself, in a terminal. No tool returns it: the token is a long-lived MFA bypass, so it is never put into a conversation.

  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.

  • 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 and kia_forget_session) 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, unless MCP_CONFIRM_ELICITATION=off. An unrecognised value is treated as refuse.

MCP_CONFIRM_ELICITATION

on

off never shows a confirmation prompt, so every client gets the MCP_CONFIRM_MODE behaviour. Set it for a client that says it can show prompts but never does (the write hangs — opencode 2.0.x). Any other value is treated as on, with a warning on stderr.

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.

MCP_HOST_CONFIRM_SECRET

unset

Set by mcp-host for this registration (it has a data dir). Used when MCP_CONFIRM_SECRET is unset and MCP_DATA_DIR is absolute: a token survives the hosted child idling out between the preview and the confirmed call, and spent tokens are recorded under the data dir so a restart cannot re-accept one.

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.

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.

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

License

MIT

Available Tools

16 tools
kia_charge_targetsA
Read-only

Read the EV charge targets (evc/gts): the target state of charge per plug type (one entry for AC, one for DC). Verified live against a real vehicle. Read-only — makes no changes.

Inputs: vehicle_key (required).

kia_forget_sessionA
Idempotent

Discard the locally stored Kia session (the remember-me token), so the next Kia call needs the one-time MFA bootstrap again. This is the recovery path when the stored token no longer works — Kia revoked it, the password changed, or the account moved to another device — and the only alternative is deleting the session file by hand. It makes NO network call: Kia is not told anything, only this machine forgets. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call makes NO network call and returns a preview plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Nothing is deleted until it is confirmed.

Inputs: confirmToken.

kia_healthcheckVerify credentials and upstream reachabilityA
Read-onlyIdempotent

Resolves the credential the way real tools do, then makes one authenticated request to Kia Connect. Reports which source supplied the credential, whether Kia Connect accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a Kia Connect-side problem'. Read-only; never returns the credential itself. Call this when a real tool fails and you want to know which hop broke.

Inputs: no named parameters.

kia_list_vehiclesA
Read-onlyIdempotent

List the vehicles enrolled on this Kia Owners account (ownr/gvl). Returns each vehicleKey — the id every other Kia tool takes — plus nickname, model year/name/trim, mileage, fuel type and telematics unit. VINs are masked to their last 6 characters.

Inputs: no named parameters.

kia_refresh_statusA

Ask the car for a fresh reading (rems/rvs, requestType 0). This WAKES THE TELEMATICS UNIT, so it is much slower than kia_vehicle_status and draws a little power — prefer the cached read unless staleness matters. Kia only acknowledges the request; it does not return the new data and gives no completion signal, so read kia_vehicle_status afterwards to see the refreshed values.

Inputs: vehicle_key.

kia_send_otpA
Destructive

Step 2 of the Kia MFA bootstrap (cmm/sendOTP): deliver a one-time passcode to the account by SMS or email. Takes the otpKey and xid from kia_start_login — it cannot run without them, which is why it has no separate confirmation gate. Ask the user which channel they want (kia_start_login reports the masked destinations Kia has on file). The passcode expires in about two minutes; expiresAt reports when.

Inputs: xid (required), otpKey (required), notifyType (required).

kia_session_statusA
Read-onlyIdempotent

Whether this server is configured and logged in to Kia: are credentials present, has the one-time MFA bootstrap been completed on this device, and which vehicle commands are registered (KIA_WRITE_MODE). Makes NO network call and returns no secret — the account email is masked, the device id is truncated, and neither the session id nor the remember-me token is ever included. Start here when a Kia tool reports it is not configured.

Inputs: no named parameters.

kia_set_charge_limitsA
Idempotent

Set the target state of charge per plug type (evc/sts). Verified against a real vehicle. The write is checked: afterwards the targets are re-read from evc/gts and compared, and the result reports whether the change actually landed. Send BOTH plug types — the list replaces the stored one, so omitting an entry drops that target. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call makes NO network call and returns a preview plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). The preview step makes no call at all, not even the baseline read.

Inputs: targets (required), vehicle_key (required), verify, confirmToken.

kia_start_chargeA
Idempotent

Ask the vehicle to start charging (evc/charge). Verified against a plugged-in vehicle: evStatus.batteryCharge goes true within ~30-60s. Requires the car to be plugged in — on an unplugged car Kia still accepts the request and nothing happens. Confirm with kia_vehicle_status rather than trusting the success status. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call makes NO network call and returns a preview plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Inputs: vehicle_key (required), chargeRatio, confirmToken.

kia_start_climateA
Idempotent

Start remote climate control / preconditioning (Kia rems/start, live-verified). Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call makes NO network call and returns a preview plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Once confirmed it sends the command and re-reads cmm/gvi until the NESTED climate.airCtrl reads true (there is no flat airCtrlOn field). On an EV engine stays false while climate runs — ign3 is the ignition proxy and is reported alongside. commandAccepted (Kia took the request) and stateConfirmed (the car actually reads running) are separate; state changes were observed to take 30–60s. TEMPERATURE IS BEST-EFFORT AND UNCONFIRMED: per docs/KIA-API.md a start requesting 70°F still read back 72°F, so the car may report its own last-set target rather than the requested one — do not promise the user a specific cabin temperature. Seat and steering-wheel/rear-window heating are not sent at all: the request body deliberately omits heatVentSeat (Kia validates seat capability per car) and leaves every heatingAccessory field at 0.

Inputs: vehicle_key (required), defrost, temperature, waitSeconds, +2 more.

kia_start_loginA
Destructive

Step 1 of the ONE-TIME Kia MFA bootstrap (prof/authUser): send the configured credentials and get back the otpKey and xid the next two steps need. Only needed when kia_session_status reports hasSession:false — once the bootstrap is done the stored remember-me token refreshes sessions silently forever. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call makes NO network call and returns a preview plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). The gate is real: Kia counts failed logins and eventually enforces reCAPTCHA, which breaks server-side login for this account PERMANENTLY — so a rejection is never retried, and a wrong password must be fixed in the environment rather than guessed at.

Inputs: confirmToken.

kia_stop_chargeA
Idempotent

Ask the vehicle to stop charging (evc/cancel). Verified against a charging vehicle: evStatus.batteryCharge goes false within ~30-60s. Confirm with kia_vehicle_status rather than trusting the success status. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call makes NO network call and returns a preview plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Inputs: vehicle_key (required), confirmToken.

kia_stop_climateA
Idempotent

Stop remote climate control (Kia rems/stop, live-verified). Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call makes NO network call and returns a preview plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Once confirmed it sends the command and re-reads cmm/gvi until the NESTED climate.airCtrl reads false (there is no flat airCtrlOn field); ign3 — the EV ignition proxy — is reported alongside. commandAccepted (Kia took the request) and stateConfirmed (the car actually reads stopped) are separate. State changes were observed to take 30–60s.

Inputs: vehicle_key (required), waitSeconds, confirmToken.

kia_vehicle_locationA
Read-onlyIdempotent

The vehicle's last known location, from the location block of the cached cmm/gvi read. This is where the telematics unit last reported being, not a live GPS fix — run kia_refresh_status first for a recent one. Latitude/longitude and a map link are derived when the block carries coord.lat/coord.lon; otherwise the raw block is returned as-is (its exact field names are not verified).

Inputs: vehicle_key.

kia_vehicle_statusA
Read-onlyIdempotent

Read the vehicle's CACHED status (cmm/gvi): door lock, ignition, and the remote-climate block. Fast, but it reports whatever the telematics unit last uploaded — use kia_refresh_status first when freshness matters. Requested with airTempRange/seatHeatCoolOption = "1" so the nested climate object is present; when it is still absent the result says so rather than reporting climate as off. Note ign3 (not engine) is the ignition on an EV, and syncDate advances on every read, so it never proves anything changed. Per-seat heat/vent state is reported under climate.seats as the RAW numbers Kia sends: the heatVentType/heatVentLevel encoding is UNVERIFIED, so do not tell the user a seat is heating, ventilating or off based on them. An absent seat block means this read carried no seat data — it does NOT mean the car lacks heated seats, which this server cannot currently determine. Pass include_raw for the untrimmed status block (battery/EV detail, doors, tyres, …).

Inputs: include_raw, vehicle_key.

kia_verify_otpA
Destructive

Step 3 of the Kia MFA bootstrap (cmm/verifyOTP): exchange the passcode for a session. The resulting remember-me token is stored locally and is NOT returned — from here on every Kia tool refreshes its own session silently and MFA is never needed again on this device. Takes the otpKey and xid from kia_start_login plus the code the user received.

Inputs: otp (required), xid (required), otpKey (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 16 tools

    Disambiguation5/5

    Every tool targets a distinct resource+action, and the descriptions explicitly resolve the few potentially confusable pairs: kia_vehicle_status vs kia_refresh_status (cached vs live), and kia_session_status vs kia_healthcheck (local config check vs authenticated probe). The three MFA tools are clearly ordered steps with explicit inputs (otpKey/xid). No two tools appear to do the same thing.

    Naming Consistency5/5

    All 16 tools follow a uniform `kia_` prefix plus a consistent snake_case verb_noun pattern (kia_start_climate, kia_stop_charge, kia_set_charge_limits, kia_get... style reads like kia_vehicle_status, kia_charge_targets). Verb style is predictable throughout with no camelCase or mixed-convention outliers.

    Tool Count4/5

    16 tools is slightly above the ideal 3-15 band but each earns its place: read vs refresh, start vs stop pairs, charge read vs write, and three distinct auth steps. The count is justified by the breadth of the domain rather than padding.

    Completeness4/5

    Auth/MFA lifecycle (start_login, send_otp, verify_otp, forget_session, session_status, healthcheck), vehicle listing, status read/refresh, location, climate and charge control are all covered. The notable gap is remote door lock/unlock and other accessory commands (horn, lights) — vehicle_status reports door lock state but no tool can change it, though agents can work around the rest.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that connects to the Tesla Fleet API, allowing AI assistants like Claude to control Tesla vehicles and access vehicle information through natural language commands.
      20
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that connects to the Tesla Fleet API, allowing users to control vehicles and retrieve real-time status updates through Claude and other AI assistants. It supports functions such as waking up vehicles, viewing detailed vehicle information, and debugging via both stdio and HTTP/SSE transports.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server combining TeslaMate historical analytics with Fleet API live data and commands. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.
      29
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP (Model Context Protocol) server that exposes Polestar 2 vehicle data to AI assistants like Claude. Query your car's battery status, vehicle info, and health data through natural conversation.
      1
      MIT