bluelink-mcp

Talk to your Hyundai or Kia.

An open-source Model Context Protocol server for Hyundai Bluelink and Kia Connect (formerly UVO). It lets Claude and other AI assistants check your car's charge, fuel, range, locks and location, and, if you allow it, pre-heat the cabin, lock the doors or start charging.

bluelink-mcp.mattoddie.dev

Quick start · Documentation · Tool reference · Contributing

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.

Tools

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 BLUELINK_USERNAME=you@example.com \
  -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.

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

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