Metadata-Version: 2.5
Name: bluelink-mcp
Version: 0.1.0
Summary: MCP server for Hyundai Bluelink, Kia Connect and Genesis remote vehicle control
Project-URL: Homepage, https://github.com/gowthamand7/bluelink-mcp
Project-URL: Issues, https://github.com/gowthamand7/bluelink-mcp/issues
Author-email: Gowthaman Thangavel <gowthamand7@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bluelink,claude,genesis,hyundai,kia,kia-connect,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Requires-Python: >=3.13
Requires-Dist: hyundai-kia-connect-api<6,>=5.3.1
Requires-Dist: mcp<2,>=1.30
Requires-Dist: python-dotenv
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# bluelink-mcp

An [MCP](https://modelcontextprotocol.io) server that lets AI assistants such as Claude read and
control your Hyundai, Kia or Genesis vehicle: lock and unlock, remote climate, charging, status,
location and trips.

It wraps the open-source
[`hyundai_kia_connect_api`](https://github.com/Hyundai-Kia-Connect/hyundai_kia_connect_api) library
and runs on your own computer. Your credentials never leave your machine except to log in to
Hyundai or Kia.

> **Disclaimer.** This project is not affiliated with, endorsed by, or supported by Hyundai, Kia or
> Genesis. It uses unofficial, reverse-engineered APIs that the manufacturers can change or block at
> any time. Remote commands act on a real vehicle. Use it at your own risk.

## Requirements

- An active Bluelink / Kia Connect / Genesis Connected Services account.
- [uv](https://docs.astral.sh/uv/) (recommended), or Python 3.13 or later with `pip`.
- An MCP client that runs local servers: Claude Desktop, Claude Code, Cursor, VS Code, and others.

Claude on the web and mobile, ChatGPT and Grok cannot start a program on your computer, so they
cannot use this server.

## Configuration

The server reads these environment variables:

| Variable | Required | Description |
|---|---|---|
| `BLUELINK_USERNAME` | yes | Account email or username. |
| `BLUELINK_PASSWORD` | yes | Account password. |
| `BLUELINK_PIN` | Hyundai or Genesis in the USA | Remote-command PIN. |
| `BLUELINK_REGION` | yes | `USA`, `Canada`, `Europe`, `Australia`, `New Zealand`, `China`, `India` or `Brazil`. |
| `BLUELINK_BRAND` | yes | `Hyundai`, `Kia` or `Genesis`. |
| `BLUELINK_LANGUAGE` | no | Default `en`. |
| `BLUELINK_TOKEN_PATH` | no | Default `~/.bluelink-mcp/token.json`. |

Values are case-insensitive. The server also reads a `.env` file from the current working
directory; real environment variables take priority. See `.env.example`.

## Add it to your client

### Claude Desktop

1. Open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json`.
2. Add a `bluelink` entry inside `mcpServers`:

   ```json
   {
     "mcpServers": {
       "bluelink": {
         "command": "uvx",
         "args": ["bluelink-mcp"],
         "env": {
           "BLUELINK_USERNAME": "you@example.com",
           "BLUELINK_PASSWORD": "your-password",
           "BLUELINK_PIN": "0000",
           "BLUELINK_REGION": "USA",
           "BLUELINK_BRAND": "Hyundai"
         }
       }
     }
   }
   ```

3. Quit Claude Desktop completely and start it again.

### Claude Code

```
claude mcp add bluelink -e BLUELINK_USERNAME=you@example.com -e BLUELINK_PASSWORD=your-password -e BLUELINK_PIN=0000 -e BLUELINK_REGION=USA -e BLUELINK_BRAND=Hyundai -- uvx bluelink-mcp
```

### Without uv

Run `pip install bluelink-mcp`, then use `bluelink-mcp` as the command instead of `uvx`.

Then ask your assistant something like "Is my car locked?"

## Tools

The server registers only the tools that your region and brand support. It logs the list at
startup.

| Area | Tools |
|---|---|
| Vehicles and status | `list_vehicles`, `get_vehicle_status`, `get_location`, `get_trip_info_month`, `get_trip_info_day`, `check_action_status` |
| Doors | `lock`, `unlock`, `door_power_off`, `open_frunk` |
| Climate | `start_climate`, `stop_climate`, `start_pet_care`, `stop_pet_care`, `start_battery_conditioning`, `stop_battery_conditioning` |
| Charging (EV/PHEV) | `start_charge`, `stop_charge`, `set_charge_limits`, `set_charging_current`, `open_charge_port`, `close_charge_port`, `set_charge_alarm`, `set_v2l_discharge_limit` |
| Other | `start_hazard_lights`, `start_hazard_lights_and_horn`, `set_windows`, `start_valet_mode`, `stop_valet_mode`, `turn_off_lamp`, `stop_rear_seat_alarm`, `set_navigation` |
| Schedules | `schedule_charging_and_climate`, `schedule_reservation_charge`, `schedule_reservation_hvac`, `schedule_reservation_engine` |
| Login (OTP regions) | `send_otp`, `verify_otp` |

For example, Hyundai USA gets 15 tools: status, location, trips, lock and unlock, climate, charging,
and hazard lights and horn.

Each vehicle's `vehicle_id` is the last 6 characters of its VIN.

### Safety: `confirm=true`

These tools send nothing unless you pass `confirm=true`: `unlock`, `start_hazard_lights_and_horn`,
`open_charge_port`, `set_windows` (when a window opens), `start_valet_mode`, `stop_valet_mode`,
`open_frunk`, `door_power_off` and `set_v2l_discharge_limit`. Without it they return a message that
names the effect, so the assistant must ask you first. They also carry the MCP destructive hint.

`start_climate` is not guarded. On gas vehicles it starts the engine.

### One-time passcode (Kia USA and others)

Some regions need a one-time passcode at login. The assistant calls `send_otp` (email or SMS), you
give it the code, and it calls `verify_otp`.

## Token file

After login the server stores the session token in `~/.bluelink-mcp/token.json`, or in
`BLUELINK_TOKEN_PATH`. The file never holds your password or PIN, and only your user account can
read it. Delete the file to force a fresh login.

## Development

```
git clone https://github.com/gowthamand7/bluelink-mcp
cd bluelink-mcp
uv venv
uv pip install -e ".[dev]"
uv run pytest
```

## License

MIT. See [LICENSE](LICENSE).
