io.github.chrischall/kiaaccess-mcp

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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

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, …).

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.