Tools

15 tools covering the full OneBusAway transit data surface — discovery, real-time operations, schedules, alerts, and block schedules:

onebusaway_find_stops

Find bus stops near a geographic location.

• Configurable search radius (default 300m, max ~1600m before results degrade)
• Optional stop code filter (the number printed on the sign, e.g. 75403)
• Returns stop ID, code, name, direction, served route IDs, and wheelchair boarding status
• limitExceeded flag signals when more stops exist beyond the returned set
• Stop IDs returned here feed directly into onebusaway_get_arrivals

onebusaway_get_arrivals

Real-time arrivals and departures at a stop.

• Configurable time window (minutesBefore, minutesAfter — defaults 5/35)
• predicted boolean distinguishes GPS-tracked estimates from schedule-only projections
• Schedule deviation in seconds (positive = late, negative = early)
• Vehicle position and stops-away count when available
• Active service alert summaries included inline
• tripId on each arrival feeds onebusaway_get_trip for vehicle tracking

onebusaway_get_trip

Real-time status and stop sequence for a specific trip.

• Journey phase (in_progress, layover_before, layover_during)
• Vehicle GPS position, heading, and schedule deviation
• Full stop sequence with GTFS arrival/departure times and distance along trip
• Optional serviceDateMs for looking up trips from a prior service day

onebusaway_get_vehicles

Real-time positions of all active vehicles for an agency.

• Returns GPS coordinates, heading, schedule deviation, and current trip for every active vehicle
• Optional routeId filter (applied client-side after fetching all agency vehicles)
• Phase and predicted flag distinguish actively-reporting vehicles from stale entries

onebusaway_search_routes

Search for routes by name or number across the instance.

• Falls back gracefully: the Puget Sound instance returns 404 on the search endpoint — onebusaway_find_routes (lat/lon) or onebusaway_list_routes_for_agency are the alternatives
• Error contract surfaces this with structured recovery hints

onebusaway_get_schedule_for_stop and onebusaway_get_schedule_for_route

Static schedule lookups — full-day timetables without real-time data.

• Date parameter (ISO 8601) defaults to today in the agency's timezone
• onebusaway_get_schedule_for_stop: all departures grouped by route and direction, with trip IDs for follow-up calls
• onebusaway_get_schedule_for_route: all trips for the route with full stop sequences and GTFS stop times

Resources

All resource data is also reachable via onebusaway_get_stop and onebusaway_get_route. Stop and route IDs use agency-prefixed format: {agencyId}_{localId} (e.g. 1_75403, 1_100259).

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

OneBusAway-specific:

• Wraps onebusaway-sdk with typed error classification (NotFound, RateLimited, ServiceUnavailable)
• Defaults to the Puget Sound instance (api.pugetsound.onebusaway.org) — works with ONEBUSAWAY_API_KEY=TEST for development
• Configurable ONEBUSAWAY_BASE_URL for any OneBusAway-compatible instance (NYC, Washington DC, Tampa, etc.)
• Server-level instructions guide agents through stop ID format, recommended workflows, and OneBusAway's limitations (no trip planning)

Agent-friendly output:

• predicted boolean on every arrival and vehicle distinguishes GPS-tracked data from schedule-only projections — agents branch on data, not string parsing
• Schedule deviation in seconds on arrivals, trips, and vehicle positions — structured for countdown timer math
• Cross-tool linkage: tripId from arrivals feeds onebusaway_get_trip; stopId from searches feeds arrivals; agencyId from list feeds vehicles and route listing
• Structured error contracts with recovery hints (onebusaway_search_routes 404 → fallback to onebusaway_find_routes or onebusaway_list_routes_for_agency)

Getting started

Add the following to your MCP client configuration file. ONEBUSAWAY_API_KEY=TEST works on the Puget Sound instance without registration.

{
  "mcpServers": {
    "onebusaway-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/onebusaway-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "ONEBUSAWAY_API_KEY": "TEST"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "onebusaway-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/onebusaway-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "ONEBUSAWAY_API_KEY": "TEST"
      }
    }
  }
}

Or with Docker: