bluelink-mcp

Talk to your Hyundai.

An open-source Model Context Protocol server for Hyundai Bluelink. 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, so it also works with Kia Connect and Genesis accounts in the regions that library supports.

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

Tools

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

Related MCP server: Tesla MCP Server

Quick start

You need a Bluelink account that works in the app, and uv or Docker.

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

Claude Desktop and other 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_* 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?"

Configuration

All settings are environment variables; example.env lists and explains them.

Which region?

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

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 Europe limits API calls per day. It is rate limited per car (BLUELINK_MIN_REFRESH_MINUTES).

• Logins are cached. Repeated password logins can get a Bluelink account temporarily blocked, so the server keeps the token in BLUELINK_TOKEN_FILE (mode 0600). The file contains your session tokens and password, so treat it like a password.

• Commands are slow. They travel over the mobile network and usually take 20–60 s. With wait=true (the default), the tool waits for the car to confirm. 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. Tools carry MCP annotations (read-only, destructive) so clients can ask before running them. 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 Bluelink account or network. See Development and the contributing guide.

License

MIT