@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
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 agencies with IDs, contact info, timezones, coverage centers, and full coverage widths in degrees
limitExceeded flags an upstream-capped list, with no pagination to fetch the rest
onebusaway_find_stops tool
lat and lon are required. The radius defaults to 300 m and caps at 1600 m. The optional query matches the stop code printed on the sign
- Each stop carries
id, code, direction, wheelchairBoarding (ACCESSIBLE / NOT_ACCESSIBLE / UNKNOWN), all routeIds, and routes with id, shortName, and agencyId where the response includes a matching reference
limitExceeded flags upstream truncation
onebusaway_search_stops tool
query (stop name fragment) required; maxCount defaults to 10 and caps at 3500. For a code from a stop sign, use onebusaway_find_stops with the stop's approximate location and code as query
- Same stop shape as
onebusaway_find_stops. limitExceeded means OneBusAway reported more matching stops than it returned
onebusaway_get_stop tool
- Single
stopId; returns the same stop record as onebusaway_find_stops
- Unknown IDs fail as
stop_not_found, with recovery via onebusaway_find_stops or onebusaway_search_stops
onebusaway_find_routes tool
lat and lon are required. The radius defaults to 500 m and caps at 1600 m. Set both latSpan and lonSpan for a box search and omit the radius. The optional query filters 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 defaults to 10 and caps at 6000
- Returns
shortName, longName, agencyId, and GTFS type. limitExceeded means OneBusAway reported more matching routes than it returned
- Search can return an empty list for a known route. Use
onebusaway_find_routes near the service area or onebusaway_list_routes_for_agency to check the agency's routes
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_list_routes_for_agency
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 is required. The window uses nonnegative integers for minutesBefore (default 5, cap 60) and minutesAfter (default 35, cap 240). For later departures, use onebusaway_get_schedule_for_stop
- Compare
predictedArrivalTime with scheduledArrivalTime for deviation at the stop. scheduleDeviation is the vehicle's current deviation in seconds, positive when late and meaningful when predicted is true
stopsAway is the queried stop's block sequence minus the vehicle's next stop block sequence. Zero can also mean unavailable
- 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 without routeIds and routes), arrivals in the onebusaway_get_arrivals shape, and alerts in the onebusaway_get_alert shape, including stop-wide alerts
- 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
- When present,
status.activeTripId identifies the trip the live status describes, and status.blockTripSequence gives its sequence within the block when available. The top-level tripId and schedule refer to the requested trip. Use a non-null blockId with 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":"<blockId from onebusaway_get_trip>","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 is the vehicle ID's agency namespace. Use the prefix of a known vehicleId from an arrival or trip. A route's operating agency can differ. The optional routeId filters that namespace's results by exact route ID
- 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, departureFromMs, and departureBeforeMs combine with AND; time bounds are non-negative integer Unix milliseconds, lower inclusive and upper exclusive. Selected results omit empty directions/routes; selection.total / returned count departure rows before/after selection
- Static schedule only; live predictions come from
onebusaway_get_arrivals
Example: {"stopId":"1_75403","routeId":"1_100259","departureFromMs":1792882800000,"departureBeforeMs":1792886400000} selects that route's departures in the given epoch interval.
onebusaway_get_schedule_for_route tool
routeId required; optional date as a real YYYY-MM-DD calendar date, default (omitted or blank) today; unknown routes fail as route_not_found
- Every trip that day with
tripId, tripHeadsign, serviceId, and its stop sequence
serviceDateMs preserves the upstream route scheduleDate, identifying the schedule's service day
- Route, stop, headsign, and service metadata resolve from references first, retaining legacy metadata and grouping fallbacks where reference fields are absent or empty
- Optional exact
tripId or departureFromSec / departureBeforeSec selects whole trips having any departure in the interval. Bounds are non-negative integer GTFS seconds from midnight, including values beyond 86400; lower inclusive, upper exclusive. selection.total / returned count trips before/after selection
- Static schedule only; live predictions come from
onebusaway_get_arrivals at a stop
Example: {"routeId":"1_100259","departureFromSec":28800,"departureBeforeSec":32400} selects trips with any departure from 08:00 inclusive to 09:00 exclusive.
For route and block schedules, a nonblank tripId cannot be combined with departure bounds. Blank optional IDs mean omitted; either bound may be omitted, and two supplied bounds must increase. Without selectors, all three tools return their complete mapped response with no selection metadata or default cap. Selection counts describe only that upstream response, not omitted upstream service; a zero match is a successful result with a notice.
Arrivals, stop context, trips, vehicles, schedules, and alerts include a validated IANA timezone; epoch clocks and date headings carry that zone explicitly. Stop tools use the queried stop's agency namespace, vehicles the requested agency, and trip/route schedules the referenced route's agency. Each alert resolves its own agency, route, trip, and stop scopes and uses their zone only when every scope resolves and agrees. Missing, invalid, unresolved, or conflicting zones use UTC, without additional requests. Epoch numbers and GTFS seconds remain unchanged, including schedule times beyond 24:00.
onebusaway://stop/{stopId} resource
- Stop record as
application/json, the same shape onebusaway_get_stop returns
stopId comes from onebusaway_find_stops or onebusaway_search_stops
onebusaway://route/{routeId} resource
- Route record as
application/json, the same shape onebusaway_get_route returns
routeId comes from onebusaway_find_routes or onebusaway_list_routes_for_agency
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
OneBusAway-specific:
- Wraps
onebusaway-sdk with typed error classification (NotFound, RateLimited, ValidationError for an upstream 400, ServiceUnavailable)
- Defaults to the Puget Sound instance (
api.pugetsound.onebusaway.org), where ONEBUSAWAY_API_KEY=TEST works for development; ONEBUSAWAY_BASE_URL points it at any other OneBusAway instance
- Stop and route IDs are agency-prefixed,
{agencyId}_{localId} (stop 1_75403, route 1_100259). Pass raw IDs from the configured instance as tool arguments. Resource URIs accept URI encoding for their ID segment
- One shared pacer, sized by
ONEBUSAWAY_RATE_LIMIT_*, queues every upstream request against the API key's budget; a call that gets no slot within the wait cap fails as retryable rate_limited with data.retryAfter, on any tool
- Transit data only, no trip planning; server-level instructions walk agents through the ID format and the common lookup chains
Agent-friendly output:
predicted on every arrival, trip, and vehicle separates GPS-tracked data from schedule-only projections
- Machine-readable times:
scheduleDeviation in seconds; arrival, stop-schedule, and update timestamps in Unix milliseconds; trip, route-schedule, and block stop times in GTFS seconds from midnight
- Chainable IDs:
stopId from the stop tools feeds arrivals, tripId feeds onebusaway_get_trip, blockId feeds onebusaway_get_block, situationIds feed onebusaway_get_alert, and agencyId feeds vehicles and route listing
- Typed error contracts whose recovery hints name the next tool to call, plus a
notice on empty or truncated results
Getting started
Public Hosted Instance
A public instance is available at https://onebusaway.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:
Self-Hosted / Local
Add the following to your MCP client configuration file. ONEBUSAWAY_API_KEY=TEST works on the Puget Sound instance without registration.
Or with npx (no Bun required):
Or with Docker:
For Streamable HTTP, set the transport and start the server:
Prerequisites
- Bun v1.4.4 or higher (or Node.js v24+).
- A OneBusAway API key.
TEST works on the Puget Sound instance for development; for production use or other instances, register at the relevant agency's developer portal.
Installation
- Clone the repository:
- Navigate into the directory:
- Install dependencies:
- Configure environment:
Configuration
See .env.example for the full list of optional overrides.
Running the server
Local development
Docker
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/onebusaway-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catch in tool logic
- Use
ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
- Register new tools and resources in the
createApp() arrays in src/index.ts
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.
Transit data from the default Puget Sound OneBusAway API, operated by Sound Transit and King County Metro, is governed by the Sound Transit Transit Data Terms of Use, and users of the hosted endpoint receive it under those terms. Key obligations:
- Clause 2: usage metrics are available on request.
- Clause 3: data is fetched live from the OneBusAway API and is not modified or cached beyond the request cycle.
- Clause 4: you agree to pass substantially similar terms through to any users you provide this data to.
- Clause 7: this server does not use Sound Transit trademarks in its name or branding.