kiaaccess-mcp

Kia Access MCP

一个模型上下文协议服务，通过 Kia Access 移动应用使用的 Kia Owners API，将 Claude 连接到你自己的 Kia 车辆：车辆状态、位置、里程表、电动汽车充电状态，以及需要确认的车门、空调和充电命令。

警告

由 AI 开发的项目。 此代码库由 Claude Code 构建并维护。没有人审查过其实现。在将其用于真实车辆之前，请先检查代码和工具权限。

注意

此服务能让一辆两吨重的物体移动，也能解锁你的汽车。 每个命令工具执行前都会要求你确认——如果客户端支持，会显示确认提示；否则会显示预览，并提供一个只能通过再次调用使用的一次性令牌（请参阅确认）——而且只有在你通过 KIA_WRITE_MODE=all 明确启用后，才会注册车门锁定／解锁功能。在更改该设置之前，请阅读车辆命令。

你可以做什么

可以向 Claude 提问，例如：

• “EV9 锁着吗？电量还有多少？”
• “把车预热到 72 度，持续十分钟”
• “我把车停在哪儿了？”
• “刷新车辆状态，然后告诉我里程表读数”

要求

• Node.js 22.5 或更高版本
• 一个已注册车辆的 Kia Owners / Kia Access 账户及其密码
• 一部手机或一个邮箱，用于接收一次性 MFA 验证码

条款确认

使用此服务即表示你接受以下事项：

1. 此服务使用你自己的 Kia 账户凭据，访问与 Kia Access 应用相同的私有 API。它无法访问其他人的车辆或账户。
2. 你使用此服务受 Kia 条款约束，与使用该应用时遵守的条款完全相同。这不是官方支持的集成，也未与 Kia 建立关联，未获其认可或赞助。
3. 命令会对物理世界中的真实车辆产生作用。 解锁后，车辆会一直处于未上锁状态，直到有人将其锁上；空调预处理会运行 HVAC 并消耗电力。你要为每条确认执行的命令负责。
4. 登录失败会造成不可逆的后果。 Kia 会统计登录失败次数（loginAttempt），并最终设置 enforceRecaptcha；此后，该账户将无法通过服务器端登录。因此，此服务绝不会重试被拒绝的凭据——请参阅登录失败时。

安装

1. 克隆并构建

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

2. 配置凭据

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 已加入 gitignore。服务绝不会记录凭据，也没有任何工具会返回你的密码。

3. 在 Claude Code 中注册

{
  "mcpServers": {
    "kiaaccess": {
      "command": "npx",
      "args": ["-y", "kiaaccess-mcp"],
      "env": {
        "KIA_USERNAME": "[email protected]",
        "KIA_PASSWORD": "your-password",
        "KIA_WRITE_MODE": "comfort"
      }
    }
  }
}

缺少凭据不会阻止服务启动——它会启动并响应 tools/list，只有当某个工具实际需要调用 Kia 时，才会报告配置错误。运行 kia_session_status 查看当前状态。

一次性 MFA 引导

Kia 会要求每台新设备提供一次性密码。此服务只需引导一次，便会将生成的记住我令牌（rmtoken）存储在 ~/.kiaaccess-mcp/session.json 中，之后会静默签发新会话——Kia 不会轮换此令牌，也不会再次要求验证。

请按以下顺序通过 Claude 运行：

1. kia_session_status — 确认凭据已就绪。如果返回 hasSession: false，请继续。
2. kia_start_login（会先要求你确认）— 发送凭据，并返回 otpKey 和 xid，以及 Kia 记录的已屏蔽电话号码／邮箱地址。
3. kia_send_otp — 选择 SMS 或 EMAIL。验证码大约两分钟后过期。
4. kia_verify_otp — 提供验证码。令牌会存储在本地，且不会返回。
5. kia_list_vehicles — 确认会话可用，并提供其他所有工具都需要的 vehicleKey（作为 vehicle_key 参数）。

若要重新开始（令牌已撤销、密码已更改或要移交设备），请运行 kia_forget_session（会先要求你确认），然后从第 2 步重复操作。

在无法查看手机的地方运行

引导流程需要人工操作一次。没有人能查看验证码的部署环境——例如远程主机——无法运行此流程，因此请先在可以查看验证码的设备上完成引导，再迁移令牌：

1. 在两台设备上，务必在引导前将 KIA_DEVICE_ID 设置为固定的 uuid。rmtoken 会绑定到设备 uuid，使用不同的 uuid 时将毫无用处；而且 kia_session_status 始终只会显示被截断的前缀，因此若让系统自动生成该值，你将无法读取所需的完整值。
2. 按上述步骤完成引导，然后在终端中自行从 ~/.kiaaccess-mcp/session.json 复制 rmtoken 值。没有任何工具会返回此值：该令牌可长期绕过 MFA，因此绝不会放入对话中。
3. 将该值作为 KIA_RMTOKEN 提供给远程部署，同时提供 KIA_USERNAME、KIA_PASSWORD 和相同的 KIA_DEVICE_ID。

KIA_RMTOKEN 的优先级高于本地会话存储中的任何值，因此部署使用的会话就是你提供的值，而不是它上次写入的值。请像保护密码一样保护此值：它可以绕过 MFA，并且与账户密码结合后可完全控制车辆。

登录失败时

不要重试。每次拒绝登录时，Kia 都会递增 loginAttempt，最终设置 enforceRecaptcha，导致该账户永久无法通过服务端登录。请先在 Kia Access 应用中确认邮箱和密码，修正 .env，重启，然后再试。

车辆命令

KIA_WRITE_MODE 决定哪些命令工具会被注册。这是结构性门控，而非运行时检查：未注册的工具无法通过任何主机权限设置或注入对话的指令调用。

KIA_WRITE_MODE	注册内容
none	仅注册读取工具和账户工具
comfort （默认）	气候控制启动／停止和充电命令
all	还注册 kia_lock_doors 和 kia_unlock_doors

无法识别的值会安全地回退到 none，并向 stderr 输出警告——拼写错误绝不能悄悄授予解锁车辆的权限。

所有命令还遵循以下两条规则：

• 需要确认。 只有你确认后才会发送任何内容。确认信息会显示即将发送的确切请求；在此之前，不会进行任何网络调用。请参阅确认。
• 已接受不等于已确认生效。 Kia 回复“成功”仅表示请求已被接受。命令生效的唯一证明是重新读取车辆状态并比较字段差异，因此结果会分别报告 commandAccepted 和 stateConfirmed。观察到的状态变化耗时 30–60 秒。

确认

每个写入工具（上述命令，以及 kia_start_login 和 kia_forget_session）都会在执行前请求确认。能够显示确认提示的客户端（Claude Code）会显示提示，其中包含确切的请求。不能显示确认提示的客户端（claude.ai、Claude Desktop）则采用两步流程：第一次调用不执行任何操作，只返回预览和一个 confirmToken；只有重复调用并携带该令牌后才会继续。令牌绑定到确切的预览请求——更改参数会导致请求被拒绝（DRAFT_CHANGED），并返回新的预览；重复使用令牌会导致第二次调用被拒绝（TOKEN_REUSED）。

变量	默认值
MCP_CONFIRM_MODE	ask-user	对于不能显示确认提示的客户端（claude.ai、Claude Desktop），写入操作的行为。ask-user：分两步进行——第一次调用不执行任何操作，只返回预览和令牌，模型必须先在聊天中获得你的批准，才能再次携带令牌调用。auto：同样分两步进行，但模型在自行查看预览后可以使用令牌。refuse：在此类客户端上拒绝写入操作。能够显示提示的客户端（Claude Code）始终会显示实际提示，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值会按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示永不显示确认提示，因此所有客户端都会采用 MCP_CONFIRM_MODE 的行为。对于声称能够显示提示、但实际上从不显示的客户端（写入操作会挂起——opencode 2.0.x），请设置此项。其他任何值都会按 on 处理，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；仅当令牌必须在服务重启后继续有效时才设置。
MCP_HOST_CONFIRM_SECRET	未设置	mcp-host 会为此注册项设置该值（它有数据目录）。当 MCP_CONFIRM_SECRET 未设置且 MCP_DATA_DIR 为绝对路径时使用：即使托管的子进程在预览与确认调用之间因空闲而退出，令牌仍会继续有效；已使用的令牌会记录在数据目录中，因此重启后也不会再次接受同一令牌。

工具

账户和会话

工具	说明
kia_session_status	是否已配置？是否已完成引导？写入模式是什么？不进行网络调用，也不涉及机密信息——邮箱已屏蔽，设备 ID 已截短。
kia_start_login	MFA 引导的第 1 步。需要确认，因为拒绝会造成不可逆的后果。
kia_send_otp	第 2 步——通过 SMS 或 EMAIL 发送密码。
kia_verify_otp	第 3 步——用密码换取已存储的会话。不返回机密信息。
kia_forget_session	丢弃已存储的令牌，以便重新运行引导流程。仅限本地操作；需要确认。

读取

工具	说明
kia_list_vehicles	列出所有已登记车辆及其 vehicleKey、昵称、车型和里程数。VIN 仅显示最后 6 个字符。
kia_vehicle_status	缓存的状态：车门锁、点火状态（ign3——在电动车上，engine 始终为 false）、嵌套的 climate 块等；使用 include_raw 可查看更多信息。速度快，但数据新鲜度取决于上次上传时间。
kia_refresh_status	唤醒远程信息处理单元以获取最新读数。速度较慢，会消耗少量电量，且本身不返回数据——之后请读取 kia_vehicle_status。
kia_vehicle_location	上次报告的位置以及地图链接。不是实时 GPS 定位。
kia_charge_targets	按插头类型列出的目标电量状态。

命令

工具	模式	说明
kia_start_climate	comfort	预先调节。温度尽力设定：车辆可能会报告自己上次设置的目标温度，而非请求的温度。
kia_stop_climate	comfort	已通过重新读取 climate.airCtrl 验证。
kia_start_charge	comfort	已验证。需要车辆已插电——未插电时，Kia 会接受请求，但不会执行任何操作。通过 evStatus.batteryCharge 确认。
kia_stop_charge	comfort	已验证。通过 evStatus.batteryCharge 确认。
kia_set_charge_limits	comfort	已验证，之后会重新读取 evc/gts 进行核对。请同时发送两种插头类型——此列表会替换已存储的列表。
kia_lock_doors	all	已通过重新读取 doorLock 验证。
kia_unlock_doors	all	会使车辆处于未上锁状态。只有在用户明确提出要求时才运行。

此处的每个端点都已在一辆 2024 EV9 上进行实时验证：读取操作以及四个车门／空调命令于 2026-07-27 验证，三个 evc/* 充电命令于 2026-07-28 在车辆已插电的情况下验证。每个命令都通过重新读取状态来确认，绝不依赖成功状态：Kia 一接受命令就会返回 statusCode: 0，此时距离车辆实际执行还要几秒；车辆未插电时，它也会返回成功，但实际上不会执行任何操作。因此，每个命令结果都会分别报告“已接受”和“已确认”。完整协议说明见 docs/KIA-API.md。

开发

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

许可证

MIT