BusTime MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BusTime MCP When is the next bus at stop 15678?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 failuresIn-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
instructionsand 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
Sign up for and activate a Bus Tracker account
Sign in, then go to My Account (upper right)
Follow the Developer API link to apply for a key
Full details: CTA Developer Center — Bus Tracker APIs
Deploying to Horizon
Push this repo to GitHub (public or private both work).
Sign in to horizon.prefect.io with GitHub and connect the repo.
On the configure screen, set:
Entrypoint:
main.py:mcpAuthentication: 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.
Set
CTA_URLandCTA_API_KEYas 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.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:mcpThis 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? |
|
| 24h |
|
| 24h |
|
| 30 min |
|
| 1h |
|
| never (real-time) |
|
| never (real-time) |
|
| never (real-time) |
|
| 24h |
|
| 2 min |
|
| 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 -vTests 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.mdRate 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 toolsaddA
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
Scored across 11 tools
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.
All bus-related tools follow a consistent 'get_<noun>' pattern, but the 'add' tool breaks this pattern entirely, resulting in moderate inconsistency.
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.
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
Related MCP Connectors
MBTA MCP — Boston real-time transit via the MBTA v3 API (api-v3.mbta.com)
CTA MCP — Chicago Transit Authority real-time trains ('L') + buses
Real-time transit stops, routes, arrivals, vehicle positions, and schedules via OneBusAway APIs.
SEPTA MCP — Philadelphia SEPTA real-time transit (www3.septa.org/api, keyless)
Related MCP Servers
- AlicenseCqualityCmaintenanceMCP server for the UK Bus Open Data Service, enabling timetable queries, stop search, route discovery, journey planning, and real-time bus tracking.1638 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceMCP server exposing live MBTA V3 transit data, with tools for routes, stops, arrivals, alerts, and vehicle positions.-
- AlicenseNot gradedqualityDmaintenanceEnables querying real-time BART and SF Muni transit data, including departures, trip planning, fares, advisories, routes, alerts, vehicle positions, and schedules, from any MCP-compatible client.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables real-time Chicago Transit Authority train and bus tracking, including arrivals, positions, and predictions for CTA 'L' trains and buses.109 npmMIT