Lviv public transport MCP: stops, timetables, routes, and live vehicle positions. No API key.
MCP Server: io.github.vbhjckfd/timetable-api-node
This Model Context Protocol (MCP) server provides Lviv public transport data via tools including stops, timetables, routes, and live vehicle positions. It does not require an API key. The repository is implemented in Node.js and is associated with CI workflow status, Node.js version configuration, and a WTFPL license.
🛠️ Key Features
Stops data
Timetables
Routes
Live vehicle positions
No API key requirement
Total tools: 8
🚀 Use Cases
Build applications that display Lviv transit schedules
Show route information and stop lists for public transport
Integrate real-time vehicle location updates
⚡ Developer Benefits
Node.js-based implementation
Consistent tool surface for MCP: stops, timetables, routes, live positions
Simple authentication: none via API key
⚠️ Limitations
Scope described as Lviv public transport only
Topics
transport-apitransporttransit
Captured live from the server via tools/list.
get_stop_realtime
Returns live arrivals at a stop: route, destination, vehicle type, minutes until arrival, and each vehicle's position. Use this as the **default tool** when the user asks about arrivals, departures, or the next bus/tram at a specific stop. Requires a numeric stop ID (shown on stop signage); use `search_stops` when you have a stop name, or `get_stops_around_location` when you have coordinates.
Parameters1
stop_id
integer
required
Municipal stop code shown on stop signage (e.g. 707). Accepts a positive integer or an equivalent digit-only string.
Finds stops by name (Ukrainian or English transliteration, case-insensitive, partial match) and returns each stop's numeric ID, coordinates, and the routes serving it. Use this as the **first step** when the user names a stop or landmark stop (e.g. "Опера", "Rynok", "Головний вокзал") and you need a stop ID for `get_stop_realtime` or `find_routes_between`. One name usually covers both sides of the street under different IDs; each is returned, and the `routes` list tells them apart. Use `get_stops_around_location` instead when you have coordinates rather than a name.
Parameters2
query
string
required
Stop name or part of it, e.g. "Ринок", "opera", "Стрийська".
limit
integer
optional
Maximum stops to return (1–25, default 10).
Raw schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 2,
"description": "Stop name or part of it, e.g. \"Ринок\", \"opera\", \"Стрийська\"."
},
"limit": {
"description": "Maximum stops to return (1–25, default 10).",
"type": "integer",
"minimum": 1,
"maximum": 25
}
},
"required": [
"query"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
find_routes_between
Lists the direct routes (no transfer) from one place to another: which stop to board, where to get off, the direction's destination, stops in between, and the walk at each end — best first, walking counted. Use when the user asks how to get from A to B, or which bus/tram goes from one place to another. Each end covers every stop within a 300 m walk of the one given, since a line's two directions often stop on opposite sides of a street under different names; `board_stop` says where to actually wait. An empty `options` list means no direct route: a transfer is needed. Requires numeric stop IDs; get them with `search_stops` or `get_stops_around_location` first. Follow up with `get_stop_realtime` on `board_stop` for live departures.
Parameters2
from_stop_id
integer
required
Stop ID where the trip starts.
to_stop_id
integer
required
Stop ID where the trip ends.
Raw schema
{
"type": "object",
"properties": {
"from_stop_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Stop ID where the trip starts."
},
"to_stop_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Stop ID where the trip ends."
}
},
"required": [
"from_stop_id",
"to_stop_id"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_route_static
Returns static route data: name, long name, vehicle type, colour, the ordered stop list for both directions, and the timetable of departures from the first stop (workday, Saturday and Sunday). Use when the user asks which stops a route serves, where it goes, or its scheduled departure times. Set `include_shapes` only when you will draw the route on a map — the polylines are large and carry nothing a text answer needs. Do NOT use this for live vehicle positions — use `get_route_realtime` instead. Requires a route short name (e.g. "T30", "32A") or numeric external ID.
Parameters2
route_name
string
required
Route short name (e.g. "T30", "32A") or numeric external ID.
include_shapes
boolean
optional
Include route polylines ([lat, lng] points per direction) for map drawing. Default false.
Raw schema
{
"type": "object",
"properties": {
"route_name": {
"type": "string",
"minLength": 1,
"description": "Route short name (e.g. \"T30\", \"32A\") or numeric external ID."
},
"include_shapes": {
"description": "Include route polylines ([lat, lng] points per direction) for map drawing. Default false.",
"type": "boolean"
}
},
"required": [
"route_name"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_route_realtime
Returns every vehicle currently running on a route: position, the destination it is heading to, and its next stop with estimated arrival. Use when the user asks "where is my tram/bus right now?", how many vehicles are running, or how far the next one is. Prefer `get_stop_realtime` when the user is at a stop and wants arrival times there. Requires a route short name (e.g. "T30", "32A") or numeric external ID.
Parameters1
route_name
string
required
Route short name (e.g. "T30", "32A") or numeric external ID.
Finds stops near a geographic point, returning each stop's numeric ID, name, coordinates, walking distance, and the routes serving it. Use this as the **first step** when the user gives an address or coordinates and you need stop IDs for `get_stop_realtime` or `find_routes_between`. Use `search_stops` instead when the user gives a stop name. Default radius is 1 000 m; narrow it (e.g. 300 m) for dense urban areas or widen it (up to 3 000 m) for rural locations.
Parameters3
latitude
number
required
Decimal latitude of the search centre, WGS84 (e.g. 49.842 for central Lviv).
longitude
number
required
Decimal longitude of the search centre, WGS84 (e.g. 24.031 for central Lviv).
radius_meters
integer
optional
Search radius in metres (50–3000, default 1000). Use ~300 for dense urban intersections, up to 3000 for suburban or rural areas.
Raw schema
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Decimal latitude of the search centre, WGS84 (e.g. 49.842 for central Lviv)."
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Decimal longitude of the search centre, WGS84 (e.g. 24.031 for central Lviv)."
},
"radius_meters": {
"description": "Search radius in metres (50–3000, default 1000). Use ~300 for dense urban intersections, up to 3000 for suburban or rural areas.",
"type": "integer",
"minimum": 50,
"maximum": 3000
}
},
"required": [
"latitude",
"longitude"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_nearby_vehicles
Returns live vehicles near a point, nearest first, each with its route, destination, and distance. Use when the user asks "what transport is near me right now?" or wants a live map around a location. Narrow with `route` when the user cares about one line; prefer `get_route_realtime` for a whole route and `get_stop_realtime` for arrival times at a stop. Requires decimal latitude and longitude (WGS84).
Parameters5
latitude
number
required
Decimal latitude of the centre point, WGS84 (e.g. 49.842 for central Lviv).
longitude
number
required
Decimal longitude of the centre point, WGS84 (e.g. 24.031 for central Lviv).
radius_meters
integer
optional
Search radius in metres (100–1000, default 500).
route
string
optional
Only vehicles on this route, by short name (e.g. "Т30", "А1"). Omit for all routes.
limit
integer
optional
Maximum vehicles to return, nearest first (1–50, default 15). `total` reports how many were in range.
Raw schema
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Decimal latitude of the centre point, WGS84 (e.g. 49.842 for central Lviv)."
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Decimal longitude of the centre point, WGS84 (e.g. 24.031 for central Lviv)."
},
"radius_meters": {
"description": "Search radius in metres (100–1000, default 500).",
"type": "integer",
"minimum": 100,
"maximum": 1000
},
"route": {
"description": "Only vehicles on this route, by short name (e.g. \"Т30\", \"А1\"). Omit for all routes.",
"type": "string",
"minLength": 1
},
"limit": {
"description": "Maximum vehicles to return, nearest first (1–50, default 15). `total` reports how many were in range.",
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"required": [
"latitude",
"longitude"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_vehicle_info
Returns details for one vehicle by ID: position, route, destination, license plate, and its upcoming stops with names and estimated arrival times. Use when the user wants to follow a particular vehicle, e.g. "where does this tram go next?" or "when will it reach X?". Vehicle IDs come from `get_route_realtime`, `get_nearby_vehicles`, or `get_stop_realtime` results. Do NOT use this to get all vehicles on a route — use `get_route_realtime` instead.
Parameters1
vehicle_id
string
required
Vehicle ID as returned by get_route_realtime, get_nearby_vehicles, or get_stop_realtime.
Raw schema
{
"type": "object",
"properties": {
"vehicle_id": {
"type": "string",
"minLength": 1,
"description": "Vehicle ID as returned by get_route_realtime, get_nearby_vehicles, or get_stop_realtime."
}
},
"required": [
"vehicle_id"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
dotenv/config is preloaded first so .env is populated before the agent
reads its configuration. The config file is newrelic.cjs (the agent is
CommonJS and this project is ESM) and holds no secrets — the key comes from the
environment. /health is excluded from transactions via rules.ignore.
The account is in the EU region; its license key starts with eu01xx and
the agent picks the collector from that prefix. Use the 40-character ingest
license key, not an NRAK-... user API key.
Cloud Run reads the key from Secret Manager:
bash
gcloud run services update timetable-api-node --region=us-central1 --project=timetable-252615 --set-secrets=NEW_RELIC_LICENSE_KEY=new-relic-license-key:latest
MCP Server
This service exposes a public read-only MCP endpoint over Streamable HTTP.
Production deployment (see cloudbuild.yaml for Cloud Run) serves REST and MCP from api.lad.lviv.ua. The main site lad.lviv.ua is the public transport website (this repo still links there in HTML sitemap and tables for people, not for the API host). Use your own origin when running locally.
LLM and /mcp flow
An MCP client (Claude, Cursor, or the MCP SDK) talks JSON-RPC over Streamable HTTP to POST /mcp. Tool handlers reuse the same Express actions as the REST API, backed by LokiJS timetable data, GTFS SQLite (via gtfs), and live GTFS-RT feeds (for example track.ua-gis.com).
POST https://api.lad.lviv.ua/mcp with Content-Type: application/jsonandAccept: application/json, text/event-stream — the Streamable HTTP transport rejects a request that does not accept both. The server is stateless: there is no session, so tools/call works on its own without an initialize first. The response arrives as a single SSE event: message frame carrying the JSON-RPC result.
Successful tool responses return a natural-language text summary inside MCP content items (type: "text") — e.g. "Stop «Площа Ринок»: 6 arrivals. Next: Т02 → «Пасічна» in 3 min." The full structured payload is in the structuredContent field (for schema-aware clients). Each structuredContent payload follows one contract:
ui_blocks point into data instead of repeating it. A map block gives the centre and zoom, and layers maps stops, vehicles and polylines to a dot path in the result; every stop and vehicle there has lat/lng, vehicles also bearing. An arrival_list block names the arrivals array to render, already sorted by arrival_minutes (null = no ETA).
Exposed tools
All tools are read-only. Stop IDs are the numeric codes on stop signs, returned as strings ("707"). Route names are the short names on vehicles ("Т30", "А1"); Latin "T30"/"A01" work too, and a bare number is read as an internal route ID. An unknown route or vehicle returns isError: true with a hint on what to pass instead.
One stop name usually covers both sides of the street under different IDs; each is returned, and routes tells them apart. get_stops_around_location returns the same stop objects plus distance_meters.
find_routes_between — example
Text summary: "3 direct routes «Площа Ринок» → «Залізничний вокзал». Best: Т01 towards «Залізничний вокзал», 8 stops, board at «Руська» (137m walk)."
Each end covers every stop within a 300 m walk (stop_ids): a line's two directions often stop on opposite sides of a street under different names, as here, where Т01 towards the station leaves from «Руська», not «Площа Ринок». Options are ranked by stops plus walking (150 m of walking weighs as one stop), one per route and direction. A direction's last stop counts as a place to get off, not to board. Only direct routes are listed; an empty options means a transfer is needed.
get_route_static — example
json
{"view":"transit_realtime","data":{"route":{"name":"Т30","long_name":"Університет - Городоцька - вул. Ряшівська","color":"#EF88AA","type":"trolleybus"},"stops":[[{"id":"101","name":"Університет","lat":49.841,"lng":24.003,"departures":["05:30","05:52"],"schedule":{"workday":["05:30","05:52","06:10"],"saturday":["07:00","07:30"],"sunday":["07:00"],"weekend":["07:00","07:30"]}},{"id":"707","name":"Стадіон Сільмаш","lat":49.838,"lng":24.021,"departures":[],"schedule":{"workday":[],"saturday":[],"sunday":[],"weekend":[]}}],[{"id":"707","name":"Стадіон Сільмаш","lat":49.838,"lng":24.021,"departures":["06:00"],"schedule":{"workday":["06:00"],"saturday":[],"sunday":[],"weekend":[]}}]],"updated_at":"2026-09-23T09:01:12Z"},"ui_blocks":[{"type":"map","data":{"center":[49.841,24.003],"zoom":13,"layers":{"stops":"data.stops"}}}]}
stops[0] is direction 0 (outbound), stops[1] direction 1 (return). departures and schedule are populated for the first stop of each direction; other stops have empty arrays. schedule.workday is Monday–Friday, schedule.saturday / schedule.sunday the two weekend days (they can differ); schedule.weekend merges both and is kept for backward compatibility; departures keeps today's schedule for backward compatibility. With include_shapes: true, data.shapes holds one [lat, lng] polyline per direction and the map block adds "polylines": "data.shapes".
route_name is the canonical short name whatever form was passed. direction indexes get_route_static's stops (0 = outbound, 1 = return) and destinations. next_stop is null when the feed has no trip update for the vehicle.
route is the route short name, falling back to the opaque GTFS route ID only when the route is missing from the local data. Either value is accepted as route_name by get_route_static and get_route_realtime. license_plate is null when the feed has none.
Prompts
Reusable instruction templates for rendering workflows. Each takes one argument, stop_id (positive integer or digits-only string).
Prompt
Use case
transit-map-view
Map-first rendering of live vehicles for a stop.
transit-arrival-list
Arrival list for a stop, sorted by ETA and grouped by route.
transit-hybrid-view
Map block first, arrival-list block second, with ETA values kept consistent across both.
Resources and resource templates
In addition to tools, the server exposes MCP resources for reference data that doesn't require a tool call:
URI
Description
timetable://about
Scope, usage, and data caveats for this server (Markdown)
timetable://reference/tools
Tools reference table (Markdown)
timetable://reference/prompts
Prompt templates catalog (Markdown)
timetable://stop/{code}
Static info for a stop by numeric code — name, coordinates, serving routes (JSON)
timetable://route/{name}
Static metadata for a route by short name — color, type, stop counts (JSON)
Security model
Public read-only (no authentication).
No mutating tools are exposed.
POST /mcp is rate-limited to 60 requests/min per IP (in-memory, resets on restart). Excess requests receive HTTP 429 with a JSON-RPC error body.
robots.txt is only a best-effort discovery hint and not a protocol contract.
REST API
All endpoints return JSON. :code is a numeric stop code; :name is a route short name (e.g. T1, 32A) or numeric external ID.
The upstream route list for a stop is sometimes behind reality. GET /stops
applies a stored override to its Маршрути column — removed routes shown red and
struck through, added ones green — and hangs the matching ?add=/?remove= on
that row's SVG and PDF links, which offline.lad.lviv.ua and pdf.lad.lviv.ua
both understand.
The route column is always clickable: click a route to drop or restore it, type
one into the + box to add it.
Overrides live in the browser's own localStorage (see
public/stopOverrides.js), not on a server — no
account to edit through, no cache to purge, an edit applies at once. The trade
is scope: an override is visible only in the browser that made it, not to
anyone else who opens /stops.
/stops.json reports sign and sign_pdf without overrides applied.
GET /stops/:code
Single stop with live realtime timetable. Short-cached (5–10 s).
Optional:skipTimetableData=1 — omit live arrivals (long-cached response).
departures — today's departure times (HH:MM), populated only for direction 0 first stop. Kept for backward compatibility.
schedule — { workday: string[], saturday: string[], sunday: string[], weekend: string[] } departure times by day type (weekend = Saturday ∪ Sunday, deprecated), populated only for direction 0 first stop.
GET /routes/dynamic/:name
Live vehicle positions for a route. Short-cached (10 s).
Response: array of { id, direction, location: [lat, lng], bearing, speed, lowfloor }. speed is m/s from the GPS unit, or null when not reported.
Vehicles
GET /vehicle/:vehicleId
Live position and upcoming stop arrivals for one vehicle. Short-cached (5 s).
Response:{ location: [lat, lng], routeId, bearing, speed, direction, licensePlate, arrivals }. speed is m/s from the GPS unit, or null when not reported.
GET /vehicle-by-plate/:plate
Look up a vehicle ID by its license plate. Short-cached (5 s).
The plate is matched case-insensitively with spaces and dashes ignored (BC-1234-AA, bc 1234 aa, and bc1234aa are all equivalent).
Response:{ vehicleId } — use the returned ID with GET /vehicle/:vehicleId.
GET /transport?latitude={lat}&longitude={lng}
Vehicles within 1 km of a point. Short-cached (10 s).
Response: array of { id, route, routeId, direction, vehicle_type, color, location: [lat, lng], bearing, speed, lowfloor }. routeId is usable as :name in /routes/static/:name; direction matches the index into stops/shapes (0 = outbound, 1 = return, null if unknown). speed is m/s or null.
