oasa-mcp

An MCP server for Athens public transport. It gives an AI assistant live bus and trolley arrivals, vehicle positions, routes, stops and timetables for the OASA network, in Greek or Latin script.

Unofficial and unaffiliated with OASA. Data belongs to OASA (Οργανισμός Αστικών Συγκοινωνιών Αθηνών).

What stop_arrivals returns:

ΠΛ. ΠΛΑΤΑΝΟΥ (PL. PLATANOY) · stop 10272 · as of 18:30 (Europe/Athens)

line  destination        in (min)  then  eta    vehicle
Χ14   ΚΗΦΙΣΙΑ (KIFISIA)        16     —  18:46  44621
500   ΚΗΦΙΣΙΑ (KIFISIA)        52     —  19:22  14439

Minutes are live OASA estimates and shift as vehicles move.

and find_stops, given a coordinate:

Stops near 37.9838, 23.7275 (within 300 m)

stop_code  name                         street  metres
60134      ΠΛ. ΟΜΟΝΟΙΑΣ (PL. OMONOIAS)  ΑΘΗΝΑΣ      60
10184      ΟΜΟΝΟΙΑ (OMONOIAS)           —           64
12750      ΣΤ. ΟΜΟΝΟΙΑ                  —           67
11395      ΟΜΟΝΟΙΑ-ΡΕΞ (OMONOIA - REX)  —           72

Install

Add it to your MCP client. Nothing to install first — npx fetches it on demand.

{
  "mcpServers": {
    "oasa": { "command": "npx", "args": ["-y", "oasa-mcp"] }
  }
}

For Claude Code:

claude mcp add oasa -- npx -y oasa-mcp

Check it works:

npx -y oasa-mcp --self-test

Requires Node 20.19 or newer. No API key — OASA's telematics API is public.

Related MCP server: TfL MCP Server

Tools

Names work in either script, with accents and case ignored, so Syntagma, ΣΥΝΤΑΓΜΑ, Σύνταγμα and syntagma are all the same query. Common English names such as Piraeus and Airport are mapped too.

When a name matches several stops the tool returns the candidates rather than picking one. Athens stop names repeat across the city, and a wrong stop would produce a confidently wrong arrival time — worse than one extra round-trip.

Scope and limits

• Attica only — OASA buses, trolleys, metro and tram. Nothing outside greater Athens.

• Empty results are normal. Outside roughly 05:00–00:30 Europe/Athens most lines do not run, so arrivals and vehicle positions legitimately come back empty. That is not an error and the tools say so explicitly.

• Arrival minutes are OASA's live estimates, not timetable times. They shift as vehicles move. Use line_schedule for scheduled departures.

• Stop search by name is best-effort, because the API has no stop-search endpoint at all — stops can only be listed per route. Two things cover the gap:

  • A name is first matched against lines whose names mention it, then against that line's stops. Line names carry the major places, so Syntagma, Omonia, Piraeus and Kifisia resolve immediately from a few cached requests.

  • Meanwhile a full index is built in the background by walking every route, and everything already fetched is folded into it, so repeated queries get cheaper and more complete.

  A minor stop whose name appears in no line name may not be found until that index fills in; the tools say so rather than implying the stop does not exist. Searching by lat/lon is always exact and immediate. OASA_PREWARM_INDEX=1 starts the index at launch.

Why this exists

OASA's telematics API has a reputation for constant downtime. Most of that is a DNS problem, not an outage.

The API is served from several addresses inside OASA's 195.46.22.88/29, steered by a DNS record with a 60-second TTL. At the time of writing that record points at 195.46.22.91, which silently drops every packet — all ports time out, 100% ICMP loss — while 195.46.22.94 answers normally and presents the genuine *.oasa.gr certificate. The failover never fired.

A client that trusts DNS therefore hangs on every call, and no amount of retrying, header tweaking or TLS impersonation helps, because the connection attempt is dropped. The only fix is to try a different address.

So this server tries the DNS answer first — it is the intended address and will be correct again once OASA repairs the record — then falls back across the rest of the block. Fallback connections still send SNI and Host for telematics.oasa.gr, so TLS must still validate against OASA's real certificate; verification is never disabled.

If OASA renumbers, OASA_ENDPOINTS overrides the list without waiting for a release.

Configuration

All optional.

Reference data (lines, routes, stops, geometry, timetables) is cached on disk, because an MCP stdio server is spawned fresh per session and the line list alone is 150 KB. If OASA is unreachable, cached reference data is still served and labelled with its age. Live arrivals and vehicle positions are never cached.

Notes on the upstream API

Collected while building this, in case they save someone else the debugging:

• HTTPS is mandatory. Port 80 completes the TCP handshake and never replies, so an http:// client hangs instead of failing. The published examples all say http://.

• getStopArrivals returns null when nothing is due — not []. getBusLocation returns "", an empty JSON string. Both mean "nothing", and both are routine overnight.

• Field types drift. Between 2026-09-24 and 2026-10-07 route_code, btime2, StopCode and others changed from string to number, while CS_LAT/CS_LNG stayed strings. StopID keeps a significant leading zero ("060134") where StopCode is 60134, so identifiers must never be coerced to numbers.

• CS_DATE has two formats: 2026-10-07 01:42:42.000 now, and Sep 24 2026 09:31:34:000AM previously — note the milliseconds joined by a colon.

• getClosestStops takes p1=latitude, p2=longitude, the opposite of what the community documentation says. Verified by observation.

• Its distance field is in degrees, not metres (0.00059 ≈ 50 m). This server ignores it and computes metres itself.

• webRouteDetails puts longitude in routed_x and latitude in routed_y.

• Greek text contains Latin homoglyphs. Real values include ΓΚΥΖH (Latin H), ΧΕΙΜΕΡΙΝO (Latin O) and ΑNWO ΠΑΤΗSIA. Searching for the correct Greek spelling fails unless you fold these, and it looks like "no such stop" rather than an encoding fault.

• getScheduleDaysMasterline returns a field whose name is the empty string.

• getDailySchedule appears defunct — {"come":[],"go":[]} for every line tried. Timetables come from getSchedLines, which needs a master-line code, a service-day code and a line code.

• Service-day codes are seasonal (currently WINTER …), so they must be looked up per line rather than hardcoded.

• Errors arrive as HTTP 200 with an {"error": "..."} body.

Actions this server does not wrap: webGetLinesWithMLInfo, getLinesAndRoutesForMl, getRoutesForLine, getMLName, getLineName, getRouteName, getDailySchedule, webGetLangs. The community API reference documents them, with the caveats above.

Development

npm install
npm run typecheck
npm test            # offline, runs against recorded fixtures
npm run build
npm run test:live   # opt-in; hits the real API
npm run record      # re-record fixtures from the live API

The unit suite never touches the network: an accidental real request throws. Fixtures in test/fixtures/ are recorded live, so tests assert against the real service rather than a guess. The live suite asserts invariants rather than values and skips on an upstream outage, so a red build always means a real regression.

Licence

MIT