# hu-transit-mcp

MCP server for **Budapest and Hungarian public transport**: BKK metro, tram, bus, trolleybus and HÉV, **MÁV trains nationwide** (including IC, EC and railjet to Wien and München) and Volánbusz. It uses the **official [BKK FUTÁR API](https://opendata.bkk.hu)** and is read-only.

[Magyarul lent ↓](#magyarul)

Ask Claude (or any MCP client) things like:

- "When does the next M2 leave Deák Ferenc tér?"
- "How do I get from Széll Kálmán tér to Nyugati tomorrow at 8:00?"
- "Is anything wrong on the M3 today?"
- "Trains from Keleti to Wien in the next 2 hours?"
- "All trains from Miskolc to Budapest tomorrow, and back?"

## Tools

| Tool | What it returns |
|---|---|
| `find_stop` | Stops and stations by name, with lines and coordinates. Stations come first |
| `departures` | Departure board: planned and live time, delay, cancellations, operator. Optional `line` filter, `start` time and `minutes` window (up to 240) |
| `plan_trip` | Trip options between two stop names or `lat,lon` points: walking, lines, transfers, live delays. Optional `time` and `arrive_by` |
| `train_connections` | All direct MÁV trains between two stations for a whole day, like a printed timetable. Works nationwide (Miskolc, Debrecen, Szeged, Pécs, Győr…). `Budapest` covers Keleti, Nyugati, Déli and Kelenföld. Hides trains that take the long way round (over 1.5× the fastest) unless `include_detours` |
| `service_alerts` | Current disruptions and diversions (BKK and MÁV) in English or Hungarian, optional `line` filter |

## Setup

1. Get a free API key at [opendata.bkk.hu](https://opendata.bkk.hu).
2. Add the server to your MCP client (requires [uv](https://docs.astral.sh/uv/)).

**Claude Code**

```bash
git clone https://github.com/kukshaus/hu-transit-mcp.git
claude mcp add hu-transit -s user -e BKK_API_KEY=your-key \
  -- uv --directory /path/to/hu-transit-mcp run hu-transit-mcp
```

**Claude Desktop** (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "hu-transit": {
      "command": "uv",
      "args": ["--directory", "/path/to/hu-transit-mcp", "run", "hu-transit-mcp"],
      "env": { "BKK_API_KEY": "your-key" }
    }
  }
}
```

On macOS you can keep the key out of config files and store it in the Keychain. The server reads it when `BKK_API_KEY` is not set:

```bash
security add-generic-password -s bkk-api-key -a "$USER" -w 'your-key'
```

## Example

```
departures("Budapest-Keleti", minutes=120)

09:20  S60  → Sülysáp
09:25  IC   → Budapest-Nyugati
09:30  rjx  → München Hbf
09:35  S80  → Gödöllő
```

## Limits

- Live predictions exist for buses, trams and trolleybuses. Metro and MÁV trains mostly show the timetable (`realtime: false`).
- `train_connections` lists direct trains only. For journeys with a change, use `plan_trip`.
- No ticket prices or sales. The API has none.

## Development

```bash
uv sync
uv run pytest
```

---

## Magyarul

MCP-szerver a **budapesti és magyarországi közösségi közlekedéshez**: BKK metró, villamos, busz, troli és HÉV, **MÁV-vonatok országosan** (IC, EC és railjet Bécsbe és Münchenbe is), valamint Volánbusz. A **hivatalos [BKK FUTÁR API](https://opendata.bkk.hu)**-t használja, csak olvas.

Kérdezd Claude-ot (vagy bármely MCP-klienst) például így:

- „Mikor indul a következő M2 a Deák Ferenc térről?”
- „Hogyan jutok el holnap 8-kor a Széll Kálmán térről a Nyugatihoz?”
- „Van ma fennakadás az M3-on?”
- „Milyen vonatok mennek a Keletiből Bécsbe a következő 2 órában?”
- „Milyen vonatok mennek holnap Miskolcról Budapestre és vissza?”

### Eszközök

| Eszköz | Mit ad vissza |
|---|---|
| `find_stop` | Megállók és állomások név szerint, járatokkal és koordinátákkal. Az állomások elöl |
| `departures` | Indulási tábla: menetrend szerinti és valós idejű indulás, késés, kimaradás, üzemeltető. Szűrhető járatra (`line`), kezdő időpontra (`start`) és időablakra (`minutes`, max. 240) |
| `plan_trip` | Útvonaltervezés két megállónév vagy `lat,lon` pont között: gyaloglás, járatok, átszállások, valós idejű késések. Opcionális `time` és `arrive_by` |
| `train_connections` | Két állomás közötti összes közvetlen MÁV-vonat egy teljes napra, mint egy menetrend. Országosan működik (Miskolc, Debrecen, Szeged, Pécs, Győr…). A `Budapest` a Keleti, Nyugati, Déli pályaudvart és Kelenföldet jelenti. A kerülő útvonalú vonatokat (a leggyorsabbnál 1,5×-nél hosszabb) elrejti, kivéve ha `include_detours` |
| `service_alerts` | Aktuális forgalmi változások és zavarok (BKK és MÁV) angolul vagy magyarul, járatra szűrhető |

### Telepítés

1. Igényelj ingyenes API-kulcsot az [opendata.bkk.hu](https://opendata.bkk.hu) oldalon.
2. Add hozzá a szervert az MCP-kliensedhez (a fenti parancsok szerint, [uv](https://docs.astral.sh/uv/) szükséges).

A kulcs a `BKK_API_KEY` környezeti változóból jön. macOS-en a Kulcskarikában is tárolhatod (`security add-generic-password -s bkk-api-key -a "$USER" -w 'kulcs'`), ekkor egyik konfigurációs fájlba sem kell beírni.

### Korlátok

- Valós idejű előrejelzés a buszokra, villamosokra és trolikra van. A metró és a MÁV-vonatok többnyire menetrend szerinti időt mutatnak (`realtime: false`).
- A `train_connections` csak közvetlen vonatokat listáz. Átszállásos utazáshoz a `plan_trip` való.
- Jegyár és jegyvásárlás nincs, az API ezt nem kínálja.

## License

MIT. Not affiliated with BKK Zrt. or MÁV. Data © BKK Zrt. via BKK FUTÁR / opendata.bkk.hu.