Hyundai Bluelink / Kia Connect

---

It's built on hyundai_kia_connect_api, the library behind the Home Assistant Kia/Hyundai integration. Hyundai and Kia work in most regions, and Genesis in some; see Compatibility. The name and settings say Bluelink (BLUELINK_*), but they cover Kia Connect too: for a Kia, set BLUELINK_BRAND=kia.

"Is the car charged, and is it locked?" The Santa Fe is at 80% (about 52 km of electric range, 610 km total with fuel) and finished charging at 06:10. All doors are locked and the windows are closed. Bluelink last heard from it 25 minutes ago.

"Warm the EV6 up for 15 minutes." Done. The Kia confirmed it, so the cabin is heating to 21 °C for 15 minutes. It's at 64%, so there's plenty of charge for that.

Note

This is an unofficial project and isn't affiliated with Hyundai, Kia or Genesis. Their APIs are undocumented and change without notice.

Tools

Tool	What it does	Needs
list_vehicles	Vehicles on the account
get_vehicle_status	Last reported battery/fuel, range, charging, climate, locks, doors, windows, tyres, warnings and charging schedule. Doesn't wake the car.
refresh_vehicle_status	Wakes the car for live data. Rate limited (see below).
get_vehicle_location	Latitude/longitude, map link and optional address	location
get_trips	A day's trips, or a month's summary
get_energy_usage	Daily energy use for driving, climate, electronics and battery care
get_command_status	Result of an earlier command
lock_vehicle	Lock the doors	writes
start_climate / stop_climate	Pre-condition the cabin: temperature, duration, defrost, heated rear window/mirrors and steering wheel, seats	writes
start_charging / stop_charging	Start or stop charging	writes
set_charge_limits	AC/DC charge limits (EVs; most plug-in hybrids don't support this)	writes
flash_hazard_lights	Flash the hazards to find the car	writes
unlock_vehicle	Unlock the doors	writes + unlock

Every tool takes an optional vehicle (name, VIN or ID). You can leave it out if the account has one car.

Quick start

You need a Hyundai Bluelink or Kia Connect account that works in the app, and uv or Docker. On Claude Desktop you need neither: see below. The defaults are for a Hyundai in Europe. For a Kia, add BLUELINK_BRAND=kia, and outside Europe set BLUELINK_REGION.

Claude Desktop extension

Download bluelink-mcp-<version>.mcpb from the latest release and open it, or drag it onto Settings → Extensions in Claude Desktop. Fill in your login, region and brand, and choose what Claude may do. One bundle works on macOS, Windows and Linux: Claude Desktop installs Python and the dependencies itself. See Claude Desktop.

Claude Code with uv (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

For a Kia, add -e BLUELINK_BRAND=kia. Other stdio clients use the same command (uv run --directory /path/to/bluelink-mcp bluelink-mcp) with the same environment variables.

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

Then ask "How's the car doing?"

bluelink-mcp is also listed in the MCP Registry as io.github.mattoddie/bluelink-mcp, so clients that browse the registry can install the Docker image (over stdio) or the Claude Desktop bundle from there.

Configuration

All settings are environment variables; example.env lists and explains them. BLUELINK_PASSWORD, BLUELINK_PIN and MCP_AUTH_TOKEN can also be read from files with BLUELINK_PASSWORD_FILE, BLUELINK_PIN_FILE and MCP_AUTH_TOKEN_FILE.

Variable	Default
BLUELINK_USERNAME, BLUELINK_PASSWORD		Your Bluelink or Kia Connect app login (required)
BLUELINK_PIN		Your app PIN. Europe needs it for remote commands.
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	Response language (Europe)
BLUELINK_ALLOW_LOCATION	false	Register get_vehicle_location
BLUELINK_LOCATION_PRECISION	4	Decimal places of latitude/longitude to return (4 is about 10 m)
BLUELINK_GEOCODE	false	Add a street address to the location via OpenStreetMap (needs location)
BLUELINK_ALLOW_WRITES	false	Register the command tools
BLUELINK_ALLOW_UNLOCK	false	Also register unlock_vehicle (needs writes)
BLUELINK_AUDIT_LOG		Record every command and live refresh as JSON Lines: a file path, or stderr
BLUELINK_MIN_REFRESH_MINUTES	10	Minimum gap between refresh_vehicle_status calls per car
BLUELINK_MIN_COMMAND_SECONDS	60	Minimum gap before sending the same command to the same car again
BLUELINK_CACHE_SECONDS	60	How long a status read is reused
BLUELINK_LOGIN_RETRY_MINUTES	5	Wait after Bluelink rejects a login before trying again
BLUELINK_TOKEN_FILE	~/.local/state/bluelink-mcp/token.json (/data/token.json in Docker)	Login token cache. Set it empty to turn caching off.
MCP_TRANSPORT	stdio (http in Docker)	stdio or http
LOG_LEVEL	info	debug, info, warning or error
MCP_HTTP_HOST, MCP_HTTP_PORT	127.0.0.1, 8080	HTTP listen address
MCP_AUTH_TOKEN		Bearer token clients must send (at least 16 characters). Required for http.
MCP_ALLOWED_HOSTS		Optional Host header allow-list for DNS rebinding protection
MCP_ALLOWED_ORIGINS		Origins browser-based clients may use, when MCP_ALLOWED_HOSTS is set

Which region and brand?

In the UK and the rest of Europe, start with europe, the classic Bluelink and Kia Connect Europe service. Some newer Hyundais and Kias use the CCI/"OneApp" backend instead. If login or status fails with europe, try europe-cci.

Not every brand is available everywhere. New Zealand is Kia only, Brazil is Hyundai only, and Genesis doesn't work with europe-cci. See the compatibility table.

Being kind to your car (and your account)

• Reads come from Bluelink, not the car. get_vehicle_status returns what the car last uploaded, which happens when it is switched off, while charging and after commands. Check last_updated_at.
• Waking the car costs something. refresh_vehicle_status makes the car's modem report in. Done often, this drains the 12V battery, and Hyundai and Kia limit API calls per day in Europe. It is rate limited per car (BLUELINK_MIN_REFRESH_MINUTES).
• Logins are cached. Repeated password logins can get an account temporarily blocked, so the server keeps the token in BLUELINK_TOKEN_FILE (mode 0600). The file contains your session tokens (not your password or PIN), so treat it like a password. After Bluelink rejects a login the server discards the cache and waits BLUELINK_LOGIN_RETRY_MINUTES before trying again.
• Commands are slow. They travel over the mobile network and usually take 20–60 s. With wait=true (the default), the tool waits up to about 60 s for the car to confirm, then returns pending with an action_id to check later; other tools keep working meanwhile. timeout means the car didn't answer, not necessarily that nothing happened.

Safety

The server is read-only unless you set BLUELINK_ALLOW_WRITES=true, and unlock_vehicle needs its own BLUELINK_ALLOW_UNLOCK=true switch. Unlocking also needs your confirmation on the server side (see Unlocking), and each command is rate limited per car. Tools carry MCP annotations (read-only, destructive) so clients can ask before running them, and BLUELINK_AUDIT_LOG records every command in an audit log. In HTTP mode every request needs the bearer token, so don't expose the port to the internet without TLS in front of it.

Documentation

Getting started	From nothing to your first question
Connecting MCP clients	Claude Code, Claude Desktop, VS Code, Cursor, Codex, stdio
Configuration	Every setting, and choosing a region and brand
Using bluelink-mcp	Example questions, cached vs live data, commands
Tool reference	Every tool and argument
Security · Deployment · Troubleshooting	Running it well

Development

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

The tests use a fake vehicle manager, so they need no car account or network. See Development and the contributing guide.

License

MIT