sar-train-mcp

An MCP 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.

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

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

{
  "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):

{
  "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 (or pip).

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:

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

For Claude Desktop, add to claude_desktop_config.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

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, sar.hhr.sa). Provided "as is" without warranty; see LICENSE.

License

MIT © Abdulrazzak Ghazal