io.github.cyanheads/transitland-mcp-server

---

Overview

Transit data from the Transitland v2 registry — the open aggregator of GTFS, GTFS-Realtime, and GBFS feeds from thousands of transit operators worldwide. Find operators, discover feeds and their license terms, and look up routes, stops, and real-time-aware departures from any MCP client. Runs as a stdio process or a local Streamable HTTP server.

Tools

Tool	Description
transitland_find_operators	Find transit operators/agencies by name, point/radius, bounding box, country/region, or Onestop ID
transitland_get_operator	Fetch the full operator record by Onestop ID — agencies, feeds, and source tags
transitland_find_feeds	Discover GTFS, GTFS-Realtime, and GBFS feeds — fetch URLs, license terms, and freshness
transitland_find_routes	Find routes by point/radius, bounding box, operator, Onestop ID, or GTFS mode
transitland_find_stops	Find stops/stations by point/radius, bounding box, Onestop ID, or operator network
transitland_get_departures	Departures from a stop, each flagged realtime true/false

Transitland does not geocode place names — resolve a location to coordinates with a geocoding MCP server (e.g. openstreetmap-mcp-server's openstreetmap_geocode) before calling a geography-filtered tool.

Resources

Resource	Description
transitland://operator/{onestop_id}	Operator record by Onestop ID — agencies, places served, published feeds, and source tags
transitland://feed/{onestop_id}	Feed record by Onestop ID — spec, fetch URL, license terms, and freshness

All resource data is also reachable via tools (transitland_get_operator, transitland_find_feeds).

Capability reference

transitland_find_operators _tool

• Filter by search (name), lat+lon+radius (max 100,000m, default 1,000m), bbox, onestop_id, or adm0_name/adm1_name (country/region) — at least one required, or the call fails as no_filter
• Returns each operator's Onestop ID, name, places served, published feeds (a GTFS_RT entry signals real-time departures may be available), and Wikidata QID
• lat requires lon and vice versa, or the call fails as incomplete_point
• limit caps at 100 (default 20), paginated via the after cursor

---

transitland_get_operator _tool

• Accepts an Onestop ID (e.g. o-9q9-bart) or an internal integer ID
• Returns agencies (each with places served), published feeds, and source tags: Wikidata QID, US NTD ID, general Twitter/X handle
• Idempotent single-record lookup; mirrored by the transitland://operator/{onestop_id} resource
• operator_not_found when the ID doesn't resolve

---

transitland_find_feeds _tool

• Filter by operator_onestop_id (from transitland_find_operators — the reliable path to one agency's feeds), spec (gtfs/gtfs-rt/gbfs/mds), search, or fetch_error — at least one required
• Each feed returns its fetch URL, real-time endpoints when present, and license terms — redistribution, commercial use, derived products, and attribution as explicit yes/no/unknown (never inferred from a blank field), plus SPDX identifier and attribution text where known
• Freshness: last-fetch timestamp, content hash, and the calendar window the current data covers
• authorizationRequired flags feeds whose download needs a separate key/registration
• limit caps at 100 (default 20), paginated via after

---

transitland_find_routes _tool

• Filter by lat+lon+radius (max 50,000m, default 1,000m), bbox, operator_onestop_id, onestop_id, route_type (GTFS mode integer), or search — at least one required
• Returns short/long name, route_type mapped to a human-readable mode (bus, subway, rail, ferry, tram, …), brand color, operating agency's Onestop ID, and source feed's Onestop ID
• Scheduled (GTFS static) route definitions, not live vehicle positions
• lat requires lon and vice versa, or the call fails as incomplete_point
• limit caps at 100 (default 20), paginated via after

---

transitland_find_stops _tool

• Filter by lat+lon+radius (max 10,000m, default 500m), bbox, onestop_id, or served_by_onestop_ids (comma-separated operator/route Onestop IDs) — at least one required
• Returns coordinates, location_type with a label (stop, station, entrance, node, boarding area), wheelchair accessibility, timezone, and the parent station's Onestop ID for child platforms
• Departures attach to platform-level stops (location_type 0) — a station may return none; use its child platforms
• limit caps at 100 (default 20), paginated via after

---

transitland_get_departures _tool

• Resolve a stop to its Onestop ID with transitland_find_stops first
• Every departure carries a realtime flag — true for a live GTFS-Realtime prediction, false for a static scheduled time — plus a scheduleRelationship (STATIC, SCHEDULED, ADDED, CANCELED, UNSCHEDULED, DUPLICATED)
• Returns scheduled and (when real-time) estimated times with delay in seconds, route, headsign, mode, trip, direction, and accessibility
• Top-level realtimeAvailable reports whether the stop's feed publishes GTFS-RT at all
• next_seconds look-ahead window: 60–86,400 (default 3,600); widen it or set use_service_window: true when a stop returns nothing
• stop_not_found when the stop doesn't resolve — detected from an empty upstream array, not an HTTP 404

---

transitland://operator/{onestop_id} _resource

• Mirrors transitland_get_operator — agencies, places served, published feeds, and source tags (Wikidata QID, US NTD ID, Twitter/X handle)
• onestop_id param accepts an Onestop ID (e.g. o-9q9-bart) or internal integer ID
• operator_not_found when the ID doesn't resolve

---

transitland://feed/{onestop_id} _resource

• Mirrors a single-feed result from transitland_find_feeds — spec, fetch URL, real-time endpoints, license terms, and latest-fetch freshness
• onestop_id param accepts a feed Onestop ID (e.g. f-9q9-bart) or internal integer ID
• License fields normalize blank registry values to unknown/null — never inferred as permissive
• feed_not_found when the ID doesn't resolve

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.

Transitland-specific:

• Direct HTTP client for the Transitland v2 REST API — no SDK dependency, a flat query-param contract over a handful of GET endpoints
• Onestop IDs (o-/f-/r-/s-) are the identifier spine — surfaced in every result, accepted on input alongside internal integer IDs
• Feed-version history sliced to the latest version (the raw endpoint returns the entire fetch log — 167 entries for BART), so a feed lookup returns current freshness, not a multi-year history
• Coverage polygons and route/stop geometry omitted by default — a compact country/region/city place summary instead

Agent-friendly output:

• The real-time distinction is structural — a per-departure realtime boolean and scheduleRelationship, plus a top-level realtimeAvailable, so an agent branches on data, never on parsing a timestamp
• License terms surfaced honestly — blank registry fields normalize to unknown/null and are never inferred as permissive; the schema descriptions tell agents to confirm against the license URL before redistributing
• The pagination meta.next URL embeds the API key in plaintext; the service discards it and surfaces only the opaque integer after cursor, so the key never reaches tool output or logs
• Empty results return data plus an actionable notice (geocode-first, widen the window, try a child platform) rather than an error

Getting started

Add the following to your MCP client configuration file. A Transitland API key is required — see Prerequisites for how to get one.

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/transitland-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TRANSITLAND_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/transitland-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TRANSITLAND_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "TRANSITLAND_API_KEY=your-api-key",
        "ghcr.io/cyanheads/transitland-mcp-server:latest"
      ]
    }
  }
}

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

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 TRANSITLAND_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• A Transitland v2 API key — register at the Transitland developer portal. The free tier is rate-limited; the Pro tier raises the quota.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd transitland-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set TRANSITLAND_API_KEY

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. A missing TRANSITLAND_API_KEY fails at startup with a banner naming the variable, not at the first tool call.

Variable	Description	Default
TRANSITLAND_API_KEY	Required. Transitland v2 API key, sent as the apikey query parameter.	—
TRANSITLAND_BASE_URL	Transitland REST API base URL. Override to pin a specific deployment or a self-hosted instance.	https://transit.land/api/v2/rest
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for the HTTP server.	3010
MCP_HTTP_ENDPOINT_PATH	HTTP endpoint path where the MCP server is mounted.	/mcp
MCP_AUTH_MODE	Authentication 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 (spans, metrics, completion logs).	false

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

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 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 transitland-mcp-server .
docker run --rm -e TRANSITLAND_API_KEY=your-key -p 3010:3010 transitland-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/transitland-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 and resources, inits the Transitland service.
src/config	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools	Tool definitions (*.tool.ts). Six tools across operators, feeds, routes, stops, and departures.
src/mcp-server/resources	Resource definitions (*.resource.ts). Operator and feed records.
src/services/transitland	Transitland v2 REST client — HTTP, apikey injection, cursor normalization, error classification, and per-endpoint typed methods.
tests/	Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md / AGENTS.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 via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap the Transitland API: validate raw → normalize to domain type → return output schema; never fabricate missing fields (especially license terms — blanks are unknown, not permissive)

Data & licensing

Transit data is provided by Transitland — an open registry aggregating GTFS, GTFS-Realtime, and GBFS feeds from thousands of operators worldwide. Products built on Transitland data must display the name "Transitland" with a link to transit.land/terms, clearly visible to end users.

Transitland aggregates feeds from thousands of operators, each of which may carry its own license and attribution requirements. Review the per-feed license terms at transit.land/terms and comply with each source feed's requirements before redistributing or publishing data obtained through this server.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.