Onebusaway MCP Server

@cyanheads/onebusaway-mcp-server Query stops, routes, real-time arrivals, vehicle positions, and schedules from OneBusAway transit APIs via MCP. STDIO or Streamable HTTP. 16 Tools • 2 Resources

Public Hosted Server: https://onebusaway.caseyjhand.com/mcp

Overview

Real-time transit from OneBusAway, set up for Puget Sound (King County Metro, Sound Transit, Pierce Transit, Community Transit, and more) and compatible with any OneBusAway instance. Find stops and routes, track live arrivals and vehicle positions, and pull schedules and service alerts.

Tools

Resources

The same data is available to tool-only clients through onebusaway_get_stop and onebusaway_get_route.

Capability reference

onebusaway_list_agencies tool

• No input; returns every agency with id, contact info, timezone, and coverageCenter / coverageSpan
• limitExceeded flags an upstream-capped list, with no pagination to fetch the rest

onebusaway_find_stops tool

• lat / lon required; radius in meters, default 300, max 1600; optional query matches the stop code printed on the sign
• Each stop carries id, code, direction, routeIds, and wheelchairBoarding (ACCESSIBLE / NOT_ACCESSIBLE / UNKNOWN); limitExceeded means more stops exist within the radius

onebusaway_search_stops tool

• query (stop name fragment or stop code) required; maxCount up to 100, default 10
• Same stop shape as onebusaway_find_stops; limitExceeded means more stops matched than maxCount

onebusaway_get_stop tool

• Single stopId; returns name, code, coordinates, direction, routeIds, and wheelchairBoarding
• Unknown IDs fail as stop_not_found, with recovery via onebusaway_find_stops or onebusaway_search_stops

onebusaway_find_routes tool

• lat / lon required; radius in meters, default 500, max 1600, or a latSpan + lonSpan box (both set) in its place; optional query by route name or number
• Each route carries shortName, longName, agencyId, GTFS type (0=tram … 5=cable_car), color, and schedule url; limitExceeded means more routes exist in the area

onebusaway_search_routes tool

• query (route name or number) required; maxCount up to 100, default 10
• Returns shortName, longName, agencyId, and GTFS type; limitExceeded means more routes matched than maxCount
• Fails as endpoint_unavailable on instances whose route-search endpoint returns 404, Puget Sound among them; use onebusaway_find_routes or onebusaway_list_routes_for_agency instead

onebusaway_get_route tool

• Single routeId; returns shortName, longName, description, agency, GTFS type, color, and schedule url
• Unknown IDs fail as route_not_found, with recovery via onebusaway_find_routes or onebusaway_search_routes

onebusaway_list_routes_for_agency tool

• agencyId required; unknown agencies fail as agency_not_found
• Every route with shortName, longName, GTFS type, color, and url; limitExceeded flags an upstream-capped list with no pagination

onebusaway_get_arrivals tool

• stopId required; the window is minutesBefore (integer 0–60, default 5) / minutesAfter (integer 0–240, default 35), with longer horizons left to onebusaway_get_schedule_for_stop; unknown stops fail as stop_not_found
• Each arrival carries predicted (false = schedule-only), scheduleDeviation in seconds (positive = late, meaningful only when predicted), predictedArrivalTime, vehiclePosition, stopsAway, and tripId
• Active alerts arrive in situations[]: those on the stop itself plus those linked from each arrival's situationIds, each once

onebusaway_get_stop_context tool

• Same input as onebusaway_get_arrivals, and the same stop_not_found / rate_limited failures; one call issues one upstream request
• Returns stop (the onebusaway_get_stop fields minus routeIds), arrivals in the onebusaway_get_arrivals shape, and alerts in the onebusaway_get_alert shape — every alert on the stop or on an arrival in the window, including stop-wide alerts no arrival in the window carries
• When the upstream response omits the stop, stop is null; a referenced alert missing from the response is left out; either way a notice names the tool to fetch it with

onebusaway_get_alert tool

• Single situationId, from onebusaway_get_arrivals (situations[].id or arrivals[].situationIds); unknown IDs fail as situation_not_found
• Returns a TPEG reason code, severity, consequenceMessage, affects (agency, route, stop, or trip scope), consequences with diversion stop IDs, and activeWindows

onebusaway_get_trip tool

• tripId required; serviceDateMs (non-negative integer, midnight local) only for a trip on a previous service day; includeSchedule (default true) adds the stop sequence with GTFS times and distanceAlongTripMeters
• status carries phase (e.g. in_progress, layover_before), predicted, position, scheduleDeviation, and nextStop; blockId (null when the trip has none) feeds onebusaway_get_block
• Fails as trip_not_found when the trip isn't active for the service date; a completed trip's times come from onebusaway_get_schedule_for_route

onebusaway_get_block tool

• Single blockId, from onebusaway_get_trip; unknown IDs fail as block_not_found
• Top-level trips, activeServiceIds, and inactiveServiceIds describe the first returned configuration; alternateConfigurations preserves every remaining configuration in order. Service IDs are calendar conditions, not a claim that a configuration operates today
• Each trip carries distanceAlongBlock, accumulatedSlackTime (layover seconds), and blockStopTimes. Optional exact tripId or departureFromSec / departureBeforeSec selects complete trips independently in every configuration, retaining empty configuration slots
• With selectors, selection.total / returned count trip occurrences across configurations; configurationCounts[0] describes the top-level configuration, then one entry per alternative

Example: {"blockId":" ","departureFromSec":86400,"departureBeforeSec":90000} selects trips with any departure from 24:00 inclusive to 25:00 exclusive, retaining their complete stop sequences.

onebusaway_get_vehicles tool

• agencyId required, unknown agencies fail as agency_not_found; optional routeId is filtered client-side after all of the agency's vehicles are fetched
• Each vehicle carries position, orientation, phase, scheduleDeviation, tripId, nextStop, and predicted (reporting real-time GPS); limitExceeded flags an upstream-capped list with no pagination
• tripId prefers the active trip; route and headsign metadata resolve only from that trip. orientation preserves counter-clockwise degrees from east (0=east, 90=north, 180=west, 270=south), not a compass bearing
• Records missing latitude or longitude are skipped: omittedWithoutPosition counts them across the agency, and omittedWithoutPositionOnRoute counts resolved matches when filtering by route. These counts are independent of upstream truncation

onebusaway_get_schedule_for_stop tool

• stopId required; optional date as a real YYYY-MM-DD calendar date, default (omitted or blank) today in the agency's timezone; unknown stops fail as stop_not_found
• Departures grouped by route and direction, each with scheduledDepartureTime and tripId
• serviceDateMs preserves the upstream schedule-date marker: query time for an omitted/blank date, instance-local midnight for an explicit date; it is not rounded to a service-day boundary
• Optional routeId, `d