# sar-train-mcp

[![CI](https://github.com/RazakGhazal/sar-train-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/RazakGhazal/sar-train-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/sar-train-mcp.svg)](https://pypi.org/project/sar-train-mcp/)
![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2.svg)

An [MCP](https://modelcontextprotocol.io) server for **Saudi passenger rail
(SAR)** — the **Haramain High-Speed Railway (HHR)** *and* the **intercity**
East/North lines. Ask an MCP-capable assistant for train times and fares in
plain language.

![Demo: asking for the cheapest Riyadh→Dammam train and its fares](docs/demo.gif)

It uses two backends, matched to how each network exposes its data (the same
split the flagship unofficial-API tools use — scrape the open part, use a real
browser for the protected part):

| Backend | Network | How | Data |
|---|---|---|---|
| **HTTP** | Haramain (HHR) | Public HTML timetable (`sar.hhr.sa`), plain GET, no auth/CAPTCHA | Schedules |
| **Headless browser** | Intercity East/North | Renders the public booking results page (`tickets.sar.com.sa`) and scrapes it | Schedules **+ fares** |

Why the split: HHR serves an open timetable, so a plain HTTP GET works. The
intercity booking API is JWT-authed with an encrypted request/response body —
rather than reverse-engineer that anti-scraping layer, we render the public
results page in headless Chromium (the browser mints the token and does the
crypto natively) and read what any visitor sees, including fares.

## Tools

| Tool | Purpose |
|------|---------|
| `list_stations()` | Haramain stations + ids |
| `search_trains(from, to, date)` | Haramain schedules (Makkah⇄Madinah). No fares — HHR gates fares behind a reCAPTCHA. |
| `list_intercity_stations()` | Intercity stations + codes (East + North) |
| `search_intercity(from, to, date)` | Intercity trains **with Economy + Business fares** (~5–10 s, headless browser). |

`date` is `YYYY-MM-DD`. Stations accept names, aliases, or codes/ids
(`"Makkah"`, `"Jeddah"`, `"Riyadh"`, `"Dammam"`, `"RYD"`, `5`, …).

## Example prompts

Once registered, ask your assistant things like:

- *"What Haramain trains run Makkah → Madinah on 2026-06-30, and which are direct?"*
- *"Cheapest Riyadh → Dammam train next Sunday — and the business-class price?"*
- *"List the SAR intercity stations."*

## Example output

![Example output: Riyadh→Dammam with fares, and Makkah→Madinah schedule](docs/example-output.png)

**`search_intercity("Riyadh", "Dammam", "2026-07-12")`** — schedules **with fares**:

```jsonc
{
  "from": "Riyadh", "to": "Dammam", "date": "2026-07-12",
  "count": 7, "currency": "SAR", "source": "tickets.sar.com.sa",
  "trains": [
    { "train": "Train 4", "departure": "05:09", "arrival": "09:19",
      "from_code": "RYD", "to_code": "DMM", "duration": "4h10m",
      "stops": 2, "economy_sar": 135, "business_sar": 240 },
    { "train": "Train 6", "departure": "07:13", "arrival": "11:22",
      "duration": "4h09m", "stops": 2, "economy_sar": 135, "business_sar": 240 }
    // … 5 more
  ]
}
```

| Train | Depart | Arrive | Duration | Stops | Economy | Business |
|-------|--------|--------|----------|-------|---------|----------|
| Train 4 | 05:09 | 09:19 | 4h10m | 2 | SAR 135 | SAR 240 |
| Train 6 | 07:13 | 11:22 | 4h09m | 2 | SAR 135 | SAR 240 |

**`search_trains("Makkah", "Madinah", "2026-06-30")`** — Haramain schedules (no fares):

```jsonc
{
  "from": "Makkah", "to": "Madinah", "date": "2026-06-30",
  "count": 22, "source": "sar.hhr.sa/timetable",
  "trains": [
    { "departure": "2026-06-30T06:00", "arrival": "2026-06-30T08:25",
      "duration": "2h25m", "stops": 2,
      "intermediate_stops": ["Al-Sulimaniyah (Jeddah)", "KAEC"] },
    { "departure": "2026-06-30T13:20", "arrival": "2026-06-30T15:35",
      "duration": "2h15m", "stops": 0, "intermediate_stops": [] }  // direct
  ]
}
```

## Coverage

- **Haramain (HHR):** Makkah · Jeddah (Al-Sulimaniyah / Airport) · KAEC · Madinah — schedules ✅, fares ❌ (reCAPTCHA)
- **East line:** Riyadh (RYD) · Abqaiq (ABQ) · Hufuf (HAF) · Dammam (DMM) — schedules ✅, **fares ✅**
- **North line:** Riyadh · Majmaah · Qassim · Hail · Al-Jouf · Qurayyat — supported, but SAR currently lists no bookable service (returns `[]`; populates when service resumes)

## Install

Requires Python ≥ 3.10 and [`uv`](https://docs.astral.sh/uv/) (or pip).

```bash
git clone https://github.com/RazakGhazal/sar-train-mcp.git
cd sar-train-mcp

# install the CLI/MCP entry point (+ Playwright for the intercity backend)
uv tool install . --with playwright

# one-time: download the headless Chromium used for intercity fares (~150 MB)
"$(uv tool dir)/sar-train-mcp/bin/playwright" install chromium
```

Then register it with your MCP client. For **Claude Code**:

```bash
claude mcp add sar-train -- "$(command -v sar-train-mcp)"
```

For **Claude Desktop**, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sar-train": { "command": "sar-train-mcp" }
  }
}
```

## Notes & limitations

- **HHR TLS quirk:** `sar.hhr.sa` negotiates a weak DH group + legacy signature;
  the HTTP client uses an `ssl` context at `SECLEVEL=0` (certificate validation
  stays on).
- **Intercity needs Chromium** (Playwright) and takes ~5–10 s/query vs. HHR's
  instant HTTP.
- **HHR fares are not available** — SAR puts a reCAPTCHA on the Haramain
  fare/booking step, which this project does not attempt to bypass. HHR is
  schedules-only; use the official site to see HHR prices.
- Scrapers are tied to the sites' current structure; if SAR redesigns, the
  parsers (`server.py` / `intercity.py`) may need updating.

## Development

```bash
pip install -e ".[test]"
pytest              # parser fixtures + resolvers + tool registration
```

Parser tests run against frozen real responses in `tests/fixtures/`. If SAR
redesigns a page, refresh the fixture and update the expected values — a failing
test is the signal that a scraper needs attention.

## Disclaimer

Unofficial and **not affiliated with, endorsed by, or connected to** Saudi
Arabia Railways (SAR), the Haramain High-Speed Railway, or the Saudi Public
Transport Authority. It reads publicly available schedule/fare pages for
personal, informational use, at low request volumes. It does not bypass
CAPTCHAs or other access controls. Always confirm times and prices and complete
bookings on the official channels ([sar.com.sa](https://www.sar.com.sa),
[sar.hhr.sa](https://sar.hhr.sa)). Provided "as is" without warranty; see
[LICENSE](LICENSE).

## License

[MIT](LICENSE) © Abdulrazzak Ghazal