Skip to main content
Glama
BusTime MCP

BusTime MCP

by countaight

BusTime MCP

An MCP server that wraps the CTA (Chicago Transit Authority) Bus Tracker API, giving MCP clients live access to CTA bus routes, stops, predictions, vehicle locations, patterns, and detours. Built with FastMCP and deployed via Prefect Horizon.

Features

  • Full coverage of the CTA Bus Tracker v3 API (routes, directions, stops, patterns, predictions, vehicles, locales, detours, enhanced detours, system time)

  • Async HTTP via httpx, with clean error handling for missing config, bad status codes, and network failures

  • In-memory TTL caching on slow-changing endpoints (routes, directions, stops, patterns, locales, detours) — real-time endpoints (predictions, vehicles, time) always hit the live API

  • Server-level instructions and per-tool descriptions designed to help MCP clients chain calls correctly (e.g. routes → directions → stops → predictions)

  • Test suite covering the HTTP layer, caching behavior, and tool parameter validation

Related MCP server: MBTA MCP

Prerequisites

  • A CTA Bus Tracker developer API key

  • A GitHub account, with this repo pushed to it (Horizon deploys from a GitHub repo)

  • A Horizon account (free personal tier)

Getting a CTA API key

  1. Sign up for and activate a Bus Tracker account

  2. Sign in, then go to My Account (upper right)

  3. Follow the Developer API link to apply for a key

Full details: CTA Developer Center — Bus Tracker APIs

Deploying to Horizon

  1. Push this repo to GitHub (public or private both work).

  2. Sign in to horizon.prefect.io with GitHub and connect the repo.

  3. On the configure screen, set:

    • Entrypoint: main.py:mcp

    • Authentication: enable this if you want to restrict access to your org rather than leaving the endpoint open — see Rate limits below for why that matters here.

    • Dependencies are auto-detected from pyproject.toml — nothing to configure manually.

  4. Set CTA_URL and CTA_API_KEY as environment variables/secrets for the deployment. Horizon's configuration screen should have a place for this; check the current UI when you get there, since the exact field wasn't fully documented at the time this was written.

  5. Click Deploy. You'll get a live URL, typically in under 60 seconds:

    https://<your-server-name>.fastmcp.app/mcp

Horizon rebuilds and redeploys automatically on every push to main, and builds preview deployments for PRs.

Verifying before you deploy

uv run fastmcp inspect main.py:mcp

This shows what Horizon will see when it runs the server — tools, resources, and prompts — so you can catch config problems locally before pushing.

Connecting a client once deployed

Once live, MCP clients connect by URL rather than by spawning a local process:

{
  "mcpServers": {
    "BusTime": {
      "url": "https://<your-server-name>.fastmcp.app/mcp"
    }
  }
}

Horizon also provides its own Inspector and ChatMCP for testing the deployed server directly in the browser before wiring up any client.

Available tools

Tool

Endpoint

Cached?

get_routes()

/getroutes

24h

get_directions(rt)

/getdirections

24h

get_stops_for_route(rt, direction)

/getstops

30 min

get_patterns(pid=, rt=)

/getpatterns

1h

get_predictions_for_stop(stpid, rt, top)

/getpredictions

never (real-time)

get_vehicle(vid)

/getvehicles

never (real-time)

get_time(unix_time=)

/gettime

never (real-time)

get_locale_list(locale=, in_locale_language=)

/getlocalelist

24h

get_detours(rt=, direction=)

/getdetours

2 min

get_enhanced_detours()

/getenhanceddetours

2 min

Typical call sequence: get_routes → get_directions(rt) → get_stops_for_route(rt, direction) → get_predictions_for_stop(stpid, rt, top). See the server's instructions string in main.py for the full call graph, including how patterns, vehicles, and detours fit in.

Known limitation: get_enhanced_detours may return an "Unsupported function" error depending on your API key — this endpoint is GTFS-RT-oriented and appears to require CTA to enable it per-account. This is a CTA-side limitation, not a bug in this server.

Caching

Cacheable endpoints use a simple in-memory TTL cache (see _cached_get in main.py) keyed by endpoint path + parameters. TTLs are set per-endpoint based on how often the underlying data actually changes.

The cache is in-memory and per-instance. It resets on restart/redeploy, and if Horizon ever runs multiple replicas of this server, each replica has its own independent cache rather than a shared one — still correct, just less effective at cutting duplicate calls than a single-instance setup.

Testing

uv sync
uv run pytest -v

Tests use pytest-asyncio (auto mode) and respx to mock HTTP calls — no real network access or live API key is needed to run them. Run this before every push, since Horizon redeploys automatically on main.

Project structure

.
├── main.py            # server entrypoint + all tool definitions
├── pyproject.toml      # dependencies (uv-managed; also read by Horizon for auto dependency detection)
├── tests/
│   ├── conftest.py     # makes main.py importable from tests/
│   └── test_main.py
└── README.md

Rate limits

CTA's Bus Tracker API defaults to a 100,000 request/day limit per key. This server's caching helps reduce call volume for slow-changing data, but there's currently no built-in tracking or backoff as you approach that limit. This matters more once deployed publicly: a hosted URL can be called by anyone who finds it, unlike a local stdio server only you can spawn — enabling Horizon's authentication option (above) is the simplest way to keep usage scoped to people you trust.

Available Tools

11 tools
addA

Add two numbers

Inputs: a (required), b (required). Returns: result

get_detoursA

Fetch active detours in the system. Optionally filter by route (rt) and, if rt is given, by direction. Check this before trusting a get_stops_for_route or get_patterns result is current, since detours can add/remove stops or shift pattern geometry.

Inputs: rt, direction. Returns: result

get_directionsA

Fetch the set of directions serviced by the specified route. Use the 'id' field (not the human-readable 'name') from a result as the 'direction' parameter for get_stops_for_route.

Inputs: rt (required). Returns: result

get_enhanced_detoursA

Fetch enhanced detour data (used by GTFS-RT systems), including affected patterns, trips, and stops. Only returns data when detour support is enabled in BusTime for this API key; may return an 'Unsupported function' error otherwise (this is a CTA-side account limitation, not a bug in this tool).

Inputs: no named parameters. Returns: result

get_locale_listA

Fetch the list of locales (languages) supported by the API. Not currently consumed by other tools here, but useful to validate a 'locale' value before it's added elsewhere.

Inputs: locale, in_locale_language. Returns: result

get_patternsA

Fetch pattern points for a comma-delimited list of pattern ids (pid, max 10), or all active patterns for a single route (rt). Provide exactly one of pid or rt, not both. Useful for drawing a route or vehicle's path on a map.

Inputs: rt, pid. Returns: result

get_predictions_for_stopA

Fetch the top number of predictions or just the latest one if not specified for buses on a specific stop. This is real-time data and is always live, never cached.

Inputs: rt (required), top (required), stpid (required). Returns: result

get_routesA

Fetch all CTA routes. This is usually the first call in a session: use the 'rt' field from each returned route as the route designator for get_directions, get_stops_for_route, get_predictions_for_stop, get_patterns, and get_detours.

Inputs: no named parameters. Returns: result

get_stops_for_routeA

Fetch all stops for a route heading in a specified direction. Use the 'stpid' field from a result as input to get_predictions_for_stop. Call get_directions(rt) first if you don't already have a valid direction id.

Inputs: rt (required), direction (required). Returns: result

get_timeA

Fetch the current BusTime system date and time. Useful for reconciling against prediction timestamps ('prdtm') from get_predictions_for_stop. Always live, never cached.

Inputs: unix_time. Returns: result

get_vehicleA

Fetch a vehicle's live location based on its id. This is real-time data and is always live, never cached. The returned 'pid' field can be passed to get_patterns to draw the vehicle's route shape.

Inputs: vid (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 11 tools

    Disambiguation2/5

    Most tools target distinct aspects of CTA bus data, but the inclusion of 'add' (add two numbers) is completely unrelated to bus time, creating confusion about the server's purpose and when to use it.

    Naming Consistency3/5

    All bus-related tools follow a consistent 'get_<noun>' pattern, but the 'add' tool breaks this pattern entirely, resulting in moderate inconsistency.

    Tool Count4/5

    With 11 tools, the count is reasonable for a bus transit API. The 'add' tool is unnecessary but does not make the set too large or too small.

    Completeness4/5

    The bus tools cover core functionality: routes, directions, stops, predictions, vehicles, time, patterns, detours, and locale. Minor gaps exist (e.g., no route search), but the surface is largely complete for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers