Transitland MCP Server

@cyanheads/transitland-mcp-server Global transit data from the Transitland v2 registry — operators, GTFS/GTFS-RT/GBFS feeds with license terms, routes, stops, and real-time-aware departures via MCP. STDIO or Streamable HTTP. 6 Tools • 2 Resources

Overview

Transit data for thousands of operators worldwide from Transitland, the open aggregator of GTFS, GTFS-Realtime, and GBFS feeds. Find operators and their feeds, and look up routes, stops, and real-time departures.

Tools

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

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

Capability reference

Page limits default to 20 and are capped at 100. A larger limit is clamped with a notice, and truncated, shown, and cap appear when a page hits the limit. Use the returned after cursor to continue.

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
• lat requires lon and vice versa, or the call fails as incomplete_point
• 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

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
• operator_not_found when the ID doesn't resolve

transitland_find_feeds tool

• Filter by operator_onestop_id (from transitland_find_operators), spec (gtfs/gtfs-rt/gbfs/mds; case and underscore/hyphen variants such as GTFS_RT are accepted), search, or fetch_error — at least one required
• Each feed returns its fetch URL, real-time endpoints, freshness (last fetch, content hash, calendar window covered), and license terms — redistribution, commercial use, derived products, and attribution as yes/no/unknown, never inferred from a blank field — plus SPDX identifier and attribution text where known
• authorizationRequired flags feeds whose download needs a separate key or registration

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
• lat requires lon and vice versa, or the call fails as incomplete_point
• Returns short/long name, GTFS mode (bus, subway, rail, ferry, tram, …), brand color, and the operating agency's and source feed's Onestop IDs. A missing route type is null with mode unknown
• Scheduled (GTFS static) route definitions, not live vehicle positions

transitland_find_stops tool

• Filter by lat+lon+radius (max 10,000m, default 500m), bbox, onestop_id, served_by_onestop_ids (comma-separated operator/route Onestop IDs), or stop-name search — at least one required. Name searches need no geocoding
• Returns coordinates (null when missing upstream), 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, so use its child platforms

transitland_get_departures tool

• Resolve a stop to its Onestop ID with transitland_find_stops first; stop_not_found when it doesn't resolve. next_seconds sets the look-ahead window: 60–86,400 (default 3,600) — widen it or set use_service_window: true when a stop returns nothing
• Every departure carries a realtime flag (true for a live GTFS-Realtime prediction, false for a scheduled time) and a scheduleRelationship (STATIC, SCHEDULED, ADDED, CANCELED, UNSCHEDULED, DUPLICATED)
• Also returns scheduled and 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

transitland://operator/{onestop_id} resource

• Mirrors transitland_get_operator — agencies, places served, published feeds, and source tags
• onestop_id accepts an Onestop ID (e.g. o-9q9-bart) or internal integer ID; operator_not_found when it 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 freshness
• onestop_id accepts a feed Onestop ID (e.g. f-9q9-bart) or internal integer ID; feed_not_found when it doesn't resolve
• Blank license fields come back as unknown/null, never inferred as permissive

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 lookups return only the latest feed version's freshness, not the full fetch history
• Coverage polygons and route/stop geometry are omitted; results carry a compact country/region/city place summary instead

Agent-friendly output:

• Real-time status is explicit: per-departure realtime and scheduleRelationship, plus a top-level realtimeAvailable
• Blank license fields come back as unknown/null, never inferred as permissive, and agents are told to confirm against the license URL before redistributing
• Upstream pagination URLs embed the API key; only the opaque after cursor is surfaced, so the key never reaches tool output or logs
• Empty results return 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

1. Navigate into the directory:

cd transitland-mcp-server

1. Install dependencies:

bun install

1. 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_AP