Hyundai Bluelink / Kia Connect

---

它基于 hyundai_kia_connect_api 构建，这是 Home Assistant Kia/Hyundai 集成所用的库。Hyundai 和 Kia 在大多数地区都可用，Genesis 则仅在部分地区可用；请参阅兼容性。名称和设置使用 Bluelink（BLUELINK_*），但也涵盖 Kia Connect：使用 Kia 时，请设置 BLUELINK_BRAND=kia。

“车充好电了吗？锁好了吗？” Santa Fe 的电量为 80%（约有 52 km 的纯电续航，加上燃油总续航为 610 km），并于 06:10 结束充电。所有车门均已上锁，车窗已关闭。Bluelink 在 25 分钟前收到过车辆的信号。

“把 EV6 预热 15 分钟。” 完成。Kia 已确认，因此车厢会加热至 21 °C，持续 15 分钟。当前电量为 64%，足够完成预热。

说明

这是一个非官方项目，与 Hyundai、Kia 或 Genesis 均无关联。它们的 API 未公开文档，且可能随时变更。

工具

工具	功能	需要
list_vehicles	账户中的车辆
get_vehicle_status	最近上报的电池/燃油、续航里程、充电、空调、车锁、车门、车窗、轮胎、警告和充电计划。不唤醒车辆。
refresh_vehicle_status	唤醒车辆以获取实时数据。调用频率受限（见下文）。
get_vehicle_location	纬度/经度、地图链接和可选地址	位置
get_trips	某一天的行程，或某个月的汇总
get_energy_usage	驾驶、空调、电子设备和电池养护的每日能耗
get_command_status	先前命令的结果
lock_vehicle	锁车门	写入
start_climate / stop_climate	预调节车厢：温度、持续时间、除霜、后窗/后视镜加热、方向盘加热和座椅加热	写入
start_charging / stop_charging	开始或停止充电	写入
set_charge_limits	AC/DC 充电上限（电动汽车；大多数插电式混合动力汽车不支持此功能）	写入
flash_hazard_lights	闪烁危险警示灯以寻找车辆	写入
unlock_vehicle	解锁车门	写入 + 解锁

每个工具都可以选择指定 vehicle（名称、VIN 或 ID）。如果账户只有一辆车，可以不填写。

快速开始

你需要一个可在应用中正常使用的 Hyundai Bluelink 或 Kia Connect 账户，以及 uv 或 Docker。使用 Claude Desktop 则两者都不需要：请见下文。默认设置适用于欧洲地区的 Hyundai。使用 Kia 时，请添加 BLUELINK_BRAND=kia；在欧洲以外的地区，请设置 BLUELINK_REGION。

Claude Desktop 扩展

从最新版本下载 bluelink-mcp-<version>.mcpb 并打开，或将其拖到 Claude Desktop 中的 设置 → 扩展。填写登录信息、地区和品牌，并选择允许 Claude 执行的操作。一个安装包可在 macOS、Windows 和 Linux 上使用：Claude Desktop 会自行安装 Python 和依赖项。参见 Claude Desktop。

使用 uv 的 Claude Code（stdio）

git clone https://github.com/mattoddie/bluelink-mcp && cd bluelink-mcp
claude mcp add bluelink \
  -e [email protected] \
  -e BLUELINK_PASSWORD='your-password' \
  -e BLUELINK_PIN=1234 \
  -e BLUELINK_ALLOW_WRITES=true \
  -- uv run --directory "$PWD" bluelink-mcp

对于 Kia，请添加 -e BLUELINK_BRAND=kia。其他 stdio 客户端使用相同命令（uv run --directory /path/to/bluelink-mcp bluelink-mcp）和相同环境变量。

Docker（Streamable HTTP）

cp example.env .env   # fill in BLUELINK_* (BLUELINK_BRAND=kia for a Kia) and a random MCP_AUTH_TOKEN (openssl rand -hex 32)
docker compose up -d
claude mcp add --transport http bluelink http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

然后询问 “车况怎么样？”

bluelink-mcp 也已列入 MCP Registry，名称为 io.github.mattoddie/bluelink-mcp，因此能够浏览该注册表的客户端可以从中安装 Docker 镜像（通过 stdio）或 Claude Desktop 安装包。

配置

所有设置均为环境变量；example.env 列出了这些变量并作出说明。BLUELINK_PASSWORD、BLUELINK_PIN 和 MCP_AUTH_TOKEN 也可以通过 BLUELINK_PASSWORD_FILE、BLUELINK_PIN_FILE 和 MCP_AUTH_TOKEN_FILE 从文件读取。

变量	默认值
BLUELINK_USERNAME、BLUELINK_PASSWORD		Bluelink 或 Kia Connect 应用的登录信息（必填）
BLUELINK_PIN		应用 PIN。在欧洲，远程命令需要此 PIN。
BLUELINK_REGION	europe	europe、europe-cci、usa、canada、australia、nz、india、china、brazil
BLUELINK_BRAND	hyundai	hyundai（Bluelink）、kia（Kia Connect / UVO）、genesis（Genesis Connect）
BLUELINK_LANGUAGE	en	响应语言（欧洲）
BLUELINK_ALLOW_LOCATION	false	注册 get_vehicle_location
BLUELINK_LOCATION_PRECISION	4	返回的经纬度小数位数（4 位约为 10 m）
BLUELINK_GEOCODE	false	通过 OpenStreetMap 为位置添加街道地址（需要启用位置功能）
BLUELINK_ALLOW_WRITES	false	注册命令工具
BLUELINK_ALLOW_UNLOCK	false	同时注册 unlock_vehicle（需要启用写入功能）
BLUELINK_AUDIT_LOG		将每条命令和实时刷新记录为 JSON Lines：可填写文件路径或 stderr
BLUELINK_MIN_REFRESH_MINUTES	10	每辆车调用 refresh_vehicle_status 的最小间隔
BLUELINK_MIN_COMMAND_SECONDS	60	再次向同一辆车发送相同命令前的最小间隔
BLUELINK_CACHE_SECONDS	60	状态读取结果的复用时长
BLUELINK_LOGIN_RETRY_MINUTES	5	Bluelink 拒绝登录后，重试前的等待时间
BLUELINK_TOKEN_FILE	~/.local/state/bluelink-mcp/token.json（Docker 中为 /data/token.json）	登录令牌缓存。将其设为空可关闭缓存。
MCP_TRANSPORT	stdio（Docker 中为 http）	stdio 或 http
LOG_LEVEL	info	debug、info、warning 或 error
MCP_HTTP_HOST、MCP_HTTP_PORT	127.0.0.1、8080	HTTP 监听地址
MCP_AUTH_TOKEN		客户端必须发送的 Bearer 令牌（至少 16 个字符）。使用 http 时必填。
MCP_ALLOWED_HOSTS		可选的 Host 标头允许列表，用于防止 DNS 重绑定
MCP_ALLOWED_ORIGINS		设置 MCP_ALLOWED_HOSTS 时，基于浏览器的客户端可使用的来源

应使用哪个地区和品牌？

在英国和欧洲其他地区，请先使用 europe，即经典的 Bluelink 和 Kia Connect Europe 服务。一些较新的 Hyundai 和 Kia 车型改用 CCI／“OneApp”后端。如果使用 europe 时登录或状态查询失败，请尝试 europe-cci。

并非所有品牌都在每个地区提供。新西兰仅支持 Kia，巴西仅支持 Hyundai，而 Genesis 不支持 europe-cci。参见兼容性表。

善待你的汽车（以及你的账户）

• 读取的数据来自 Bluelink，而非汽车。 get_vehicle_status 返回汽车上次上传的数据，上传通常发生在汽车关闭时、充电期间以及执行命令后。请检查 last_updated_at。
• 唤醒汽车需要付出代价。 refresh_vehicle_status 会让汽车的调制解调器报告状态。频繁执行会耗尽 12V 电池，而且 Hyundai 和 Kia 会限制欧洲地区的每日 API 调用次数。该工具会按每辆车进行速率限制（BLUELINK_MIN_REFRESH_MINUTES）。
• 登录信息会被缓存。 反复使用密码登录可能导致账户被临时封锁，因此服务会将令牌保存在 BLUELINK_TOKEN_FILE（模式 0600）中。该文件包含你的会话令牌（而非密码或 PIN），请像保护密码一样保护它。Bluelink 拒绝登录后，服务会丢弃缓存，并等待 BLUELINK_LOGIN_RETRY_MINUTES 后再试。
• 命令执行较慢。 命令会通过移动网络传输，通常需要 20–60 s。使用 wait=true（默认值）时，工具最多等待约 60 s，等待汽车确认；之后会返回 pending 和一个可供稍后查询的 action_id；与此同时，其他工具仍可正常工作。timeout 表示汽车没有响应，并不一定意味着什么都没发生。

安全

除非将 BLUELINK_ALLOW_WRITES=true，否则该服务为只读；unlock_vehicle 还需要单独启用 BLUELINK_ALLOW_UNLOCK=true。解锁还需要你在服务端进行确认（参见解锁），并且每条命令都会按每辆车进行速率限制。工具带有 MCP 注释（只读、有破坏性），因此客户端可以在运行前征求确认；BLUELINK_AUDIT_LOG 会在审计日志中记录每条命令。在 HTTP 模式下，每个请求都需要 bearer 令牌，因此请勿在未配置 TLS 的情况下将端口暴露到互联网。

文档

入门	从零开始提出你的第一个问题
连接 MCP 客户端	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio
配置	所有设置，以及如何选择地区和品牌
使用 bluelink-mcp	示例问题、缓存数据与实时数据、命令
工具参考	所有工具和参数
安全 · 部署 · 故障排除	良好运行指南

开发

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .

测试使用模拟车辆管理器，因此无需汽车账户或网络。请参阅开发和贡献指南。

许可证

MIT