io.github.cyanheads/onebusaway-mcp-server

Official15 tools

by cyanheads · TypeScript

Real-time transit stops, routes, arrivals, vehicle positions, and schedules via OneBusAway APIs.

Real-time public transit information including stops, routes, arrivals, and vehicle positions.

Topics

aibungtfsmcpmcp-servermodel-context-protocolonebusawayreal-timetransitpuget-soundcyanheads

Captured live from the server via tools/list.

onebusaway_list_agencies

List all transit agencies served by this OneBusAway instance. Returns agency IDs, names, contact info, timezone, and geographic coverage center. Agency IDs are needed for onebusaway_list_routes_for_agency and onebusaway_get_vehicles.

No parameters.

onebusaway_find_stops

Find bus stops near a location. Returns stops within a radius, each with ID, name, direction, served routes, and wheelchair boarding status. Use stopId values from results to fetch real-time arrivals with onebusaway_get_arrivals. Optionally filter by stop code (the number printed on the stop sign, e.g. "75403").

Parameters (4)

latnumberrequired
Latitude of the search center.
lonnumberrequired
Longitude of the search center.
radiusnumber
Search radius in meters. Defaults to 300m. Max ~1600m before results degrade.
querystring
Optional stop code filter (the number printed on the stop sign, e.g. "75403"). When provided, returns only stops matching this code within the radius.

onebusaway_find_routes

Find transit routes near a location, optionally filtered by name or number. Returns routes with IDs, short names, and descriptions. Use routeId values to fetch schedules, vehicles, or stop sequences.

Parameters (4)

latnumberrequired
Latitude of the search center.
lonnumberrequired
Longitude of the search center.
radiusnumber
Search radius in meters. Defaults to 500m.
querystring
Filter by route name or number (e.g. "44" or "Link Light Rail").

onebusaway_search_stops

Search for stops by name or code. Returns matching stops with IDs and coordinates. Use to resolve a human-readable stop name or number to a stop ID for arrivals lookups with onebusaway_get_arrivals.

Parameters (2)

querystringrequired
Stop name fragment or stop code (e.g. "University Way" or "75403").
maxCountnumber
Maximum number of results to return. Defaults to 10.

onebusaway_search_routes

Search for routes by name or number. Returns matching routes with IDs. Use to resolve a route short name (e.g. "44") to a route ID for schedule or vehicle lookups with onebusaway_get_vehicles or onebusaway_get_schedule_for_route.

Parameters (2)

querystringrequired
Route name or number (e.g. "44", "Link", or "RapidRide").
maxCountnumber
Maximum number of results to return. Defaults to 10.

onebusaway_get_stop

Fetch details for a specific stop by ID. Returns the stop's name, coordinates, direction, served routes, and wheelchair accessibility. Stop IDs use agency-prefixed format: {agencyId}_{localId} (e.g. "1_75403" for Metro Transit stop 75403).

Parameters (1)

stopIdstringrequired
Agency-prefixed stop ID (e.g. "1_75403" for Metro Transit stop 75403, "40_100239" for Sound Transit). Use onebusaway_find_stops or onebusaway_search_stops to discover IDs.

onebusaway_get_route

Fetch details for a specific route by ID. Returns short name, description, agency, route type, and schedule URL. Route IDs use agency-prefixed format: {agencyId}_{localId} (e.g. "1_100259").

Parameters (1)

routeIdstringrequired
Agency-prefixed route ID (e.g. "1_100259"). Use onebusaway_find_routes or onebusaway_search_routes to discover IDs.

onebusaway_list_routes_for_agency

List all routes operated by an agency. Returns route IDs, short names, and descriptions. Use to enumerate an agency's full service before searching for a specific route. Get agencyId values from onebusaway_list_agencies.

Parameters (1)

agencyIdstringrequired
Agency ID (e.g. "1" for Metro Transit, "40" for Sound Transit). Use onebusaway_list_agencies to discover IDs.

onebusaway_get_arrivals

Real-time arrivals and departures at a stop. Returns predicted arrival times, schedule deviation (how many seconds late/early), vehicle positions, and any active service alerts. The predicted boolean on each arrival indicates whether GPS tracking backs the estimate — predicted=false means schedule-only. Use tripId from results for follow-up onebusaway_get_trip calls. Stop IDs use agency-prefixed format: {agencyId}_{localId} (e.g. "1_75403").

Parameters (3)

stopIdstringrequired
Agency-prefixed stop ID (e.g. "1_75403" for Metro Transit stop 75403). Use onebusaway_find_stops or onebusaway_search_stops to discover IDs.
minutesBeforenumber
Include arrivals that departed up to this many minutes ago. Defaults to 5.
minutesAfternumber
Include arrivals expected within the next N minutes. Defaults to 35.

onebusaway_get_alert

Fetch full detail for a service alert (situation) by ID. Returns the summary, description, reason (e.g. detour, construction), affected stops and routes, consequence description, and active time windows. Situation IDs appear in onebusaway_get_arrivals responses under situationIds and situations[].id.

Parameters (1)

situationIdstringrequired
Situation/alert ID from onebusaway_get_arrivals (situations[].id or arrivals[].situationIds[]).

onebusaway_get_trip

Real-time status and stop sequence for a trip. Returns vehicle position, schedule deviation, current phase, and remaining stops. Use tripId from onebusaway_get_arrivals to look up a specific vehicle's progress.

Parameters (3)

tripIdstringrequired
Trip ID from an arrivals response or schedule lookup.
serviceDateMsnumber
Service date as Unix milliseconds (midnight local time). Only needed for trips from a previous service day. Omit to use today.
includeScheduleboolean
Whether to include the full stop sequence with times. Defaults to true.

onebusaway_get_block

Fetch the full-day block schedule for a vehicle by block ID. A block is the ordered sequence of trips a single vehicle makes in one service day. Returns all trips in order with their stop times. Useful for 'when will this bus return?' and fleet tracking. Block IDs appear in onebusaway_get_trip responses under the schedule block field; obtain a tripId from onebusaway_get_arrivals first.

Parameters (1)

blockIdstringrequired
Block ID from a trip record. Obtain a tripId from onebusaway_get_arrivals, then call onebusaway_get_trip to get the blockId.

onebusaway_get_vehicles

Real-time positions of all active vehicles for an agency. Optionally filter to a single route (client-side). Returns GPS coordinates, heading, schedule deviation, and current trip. Useful for "where are all the buses on route X right now?" Use agencyId values from onebusaway_list_agencies.

Parameters (2)

agencyIdstringrequired
Agency ID (e.g. "1" for Metro Transit, "40" for Sound Transit). Use onebusaway_list_agencies to discover IDs.
routeIdstring
Optional agency-prefixed route ID to filter results to one route. Filtering is client-side — all agency vehicles are fetched first.

onebusaway_get_schedule_for_stop

Full-day departure schedule for a stop. Lists every departure by route and direction for the specified date (defaults to today). Useful for planning or when real-time data isn't needed. For live predictions, use onebusaway_get_arrivals instead.

Parameters (2)

stopIdstringrequired
Agency-prefixed stop ID (e.g. "1_75403"). Use onebusaway_find_stops or onebusaway_search_stops to discover IDs.
datestring
ISO 8601 date (e.g. "2026-05-23"). Defaults to today in the agency's timezone.

onebusaway_get_schedule_for_route

Full-day schedule for a route — all trips, stop sequences, and departure times for the specified date (defaults to today). Returns up to all trips for the route. For live predictions, use onebusaway_get_arrivals at specific stops instead.

Parameters (2)

routeIdstringrequired
Agency-prefixed route ID (e.g. "1_100259"). Use onebusaway_find_routes or onebusaway_search_routes to discover IDs.
datestring
ISO 8601 date (e.g. "2026-05-23"). Defaults to today.

README.md15 KBView on GitHub

<div align="center"> <h1>@cyanheads/onebusaway-mcp-server</h1> <p><b>Query stops, routes, real-time arrivals, vehicle positions, and schedules from OneBusAway transit APIs via MCP. STDIO or Streamable HTTP.</b> <div>15 Tools • 2 Resources</div> </p> </div> <div align="center">

</div> <div align="center">

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

</div>

Tools

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

Tool	Description
`onebusaway_list_agencies`	List all transit agencies on this OneBusAway instance with IDs, contact info, and geographic coverage
`onebusaway_find_stops`	Find bus stops near a lat/lon within a configurable radius, optionally filtered by stop code
`onebusaway_search_stops`	Search stops by name or code string to resolve a human-readable name to a stop ID
`onebusaway_get_stop`	Fetch details for a specific stop by agency-prefixed ID
`onebusaway_find_routes`	Find transit routes near a lat/lon, optionally filtered by name or number
`onebusaway_search_routes`	Search routes by name or number to resolve a route short name to a route ID
`onebusaway_get_route`	Fetch details for a specific route by agency-prefixed ID
`onebusaway_list_routes_for_agency`	List all routes operated by an agency
`onebusaway_get_arrivals`	Real-time arrivals and departures at a stop — GPS-tracked predictions, schedule deviation, vehicle positions, and active alerts
`onebusaway_get_trip`	Real-time status and full stop sequence for an active trip
`onebusaway_get_vehicles`	Real-time positions of all active vehicles for an agency, optionally filtered to one route
`onebusaway_get_schedule_for_stop`	Full-day departure schedule for a stop by route and direction
`onebusaway_get_schedule_for_route`	Full-day schedule for a route — all trips and stop sequences
`onebusaway_get_alert`	Fetch full service alert detail by situation ID — summary, description, reason, affected stops/routes, consequence, and active time windows
`onebusaway_get_block`	Fetch the full-day block schedule for a vehicle by block ID — all trips in order with stop times, useful for fleet tracking

`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

Type	Name	Description
Resource	`onebusaway://stop/{stopId}`	Stop metadata — name, coordinates, served routes, and wheelchair accessibility
Resource	`onebusaway://route/{routeId}`	Route metadata — short name, description, agency, and schedule URL

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.

json

{
  "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):

json

{
  "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:

json

{
  "mcpServers": {
    "onebusaway-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "ONEBUSAWAY_API_KEY=TEST",
        "ghcr.io/cyanheads/onebusaway-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 ONEBUSAWAY_API_KEY=TEST bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.3.0 or higher (or Node.js v24+).
An 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:

git clone https://github.com/cyanheads/onebusaway-mcp-server.git

Navigate into the directory:

cd onebusaway-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env — set ONEBUSAWAY_API_KEY if needed

Configuration

All configuration is validated at startup via Zod schemas. Key environment variables:

Variable	Description	Default
`ONEBUSAWAY_API_KEY`	OneBusAway API key. `TEST` works on Puget Sound for development.	`TEST`
`ONEBUSAWAY_BASE_URL`	Base URL for the OneBusAway instance.	`https://api.pugetsound.onebusaway.org`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	HTTP server port.	`3010`
`MCP_HTTP_ENDPOINT_PATH`	HTTP endpoint path.	`/mcp`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `notice`, `warning`, `error`).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`.	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run the production version:

# One-time build
bun run rebuild

# Run the built server
bun run start:http
# or
bun run start:stdio

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security, changelog sync
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t onebusaway-mcp-server .
docker run --rm -e ONEBUSAWAY_API_KEY=TEST -p 3010:3010 onebusaway-mcp-server

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

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools/resources and inits the OneBusAway service.
`src/config/server-config.ts`	Server-specific env var parsing: `ONEBUSAWAY_API_KEY`, `ONEBUSAWAY_BASE_URL`.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`). 13 tools across discovery, real-time, and schedule operations.
`src/mcp-server/resources`	Resource definitions (`*.resource.ts`). Stop and route metadata resources.
`src/services/onebusaway`	OneBusAway service — wraps `onebusaway-sdk`, typed error classification, domain types.
`tests/`	Unit and integration tests mirroring `src/`. 77 tests covering all tools and resources.

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 and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

Data

Transit data is sourced from the Puget Sound OneBusAway API, operated by Sound Transit and King County Metro. Use of this data is governed by the Sound Transit Transit Data Terms of Use.

Downstream users of this server's hosted endpoint receive data subject to those terms. Key obligations include:

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 through substantially similar terms to any users you provide this data to.
Clause 7 — This server does not use Sound Transit trademarks in its name or branding.

License

Apache-2.0 — see LICENSE for details.

Install

Configuration

Environment variables

ONEBUSAWAY_API_KEYdefault TEST

OneBusAway API key. TEST works on the Puget Sound instance for development.

ONEBUSAWAY_BASE_URLdefault https://api.pugetsound.onebusaway.org

Base URL for the OneBusAway instance. Defaults to Puget Sound.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "onebusaway-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/onebusaway-mcp-server@0.1.10",
        "run",
        "start:stdio"
      ],
      "env": {
        "ONEBUSAWAY_API_KEY": "TEST",
        "ONEBUSAWAY_BASE_URL": "https://api.pugetsound.onebusaway.org",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Topics

onebusaway_list_agencies

onebusaway_find_stops

onebusaway_find_routes

onebusaway_search_stops

onebusaway_search_routes

onebusaway_get_stop

onebusaway_get_route

onebusaway_list_routes_for_agency

onebusaway_get_arrivals

onebusaway_get_alert

onebusaway_get_trip

onebusaway_get_block

onebusaway_get_vehicles

onebusaway_get_schedule_for_stop

onebusaway_get_schedule_for_route

Tools

onebusaway_find_stops

onebusaway_get_arrivals

onebusaway_get_trip

onebusaway_get_vehicles

onebusaway_search_routes

onebusaway_get_schedule_for_stop and onebusaway_get_schedule_for_route

Resources

Features

Getting started

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

Data

License

Install

Configuration

`onebusaway_find_stops`

`onebusaway_get_arrivals`

`onebusaway_get_trip`

`onebusaway_get_vehicles`

`onebusaway_search_routes`

`onebusaway_get_schedule_for_stop` and `onebusaway_get_schedule_for_route`