transport_gzm

MCP server wrapping the GTFS-RT live transit feed for GZM (Górnośląsko-Zagłębiowska Metropolia) — the Silesian Metropolis public transport operator in Poland.

Provides a small, focused set of tools so AI agents can answer questions like:

• "What buses/trams are currently running on route X?"
• "Is vehicle Y delayed? Where is it right now?"
• "What alerts are currently active (delays, disruptions, works)?"
• "When does the next departure of line 6 arrive at stop Z?"

How it works

GZM publishes a public GTFS-RT feed at https://gtfsrt.transportgzm.pl:5443/gtfsrt/gzm (no auth, CC-BY licensed). It exposes three logical sub-feeds:

Path	Content
/gtfsrt/gzm/all	full bundle (all three sub-feeds)
/gtfsrt/gzm/vehiclePositions	live GPS positions of every vehicle
/gtfsrt/gzm/tripUpdates	arrival-time deltas and stop-skips
/gtfsrt/gzm/alerts	service alerts (works, delays, etc.)

This server fetches the protobuf, decodes it, and exposes it as 8 tools that return JSON-friendly structures sized for LLM context windows.

Quick start

Run with Docker (recommended)

docker run -i --rm ghcr.io/wiktor102/transport-gzm:latest

Wire it into your MCP client (Claude Desktop, opencode, …):

{
  "mcpServers": {
    "transport-gzm": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/wiktor102/transport-gzm:latest"]
    }
  }
}

Run from source

pip install -e .
transport-gzm

…or with uv:

uv run --with mcp[cli] --with gtfs-realtime-bindings --with httpx \
  python -m transport_gzm.server

Tools

Tool	Purpose
health	Check feed availability + report feed age
feed_summary	Counts of vehicles, trips, alerts currently in the feed
vehicles	Search/filter live vehicle positions (by route, stop)
vehicle_by_id	Get a single vehicle's current position
trip_updates	Arrival predictions; filter by route, stop, or trip
next_arrivals	Upcoming arrivals at a stop — like a digitalt board
alerts	Active service alerts (works, delays, detours)
alert_by_id	One alert by id

See docs/tools.md for full parameter documentation and output schemas.

Configuration

Env var	Default	Purpose
GZM_FEED_BASE_URL	https://gtfsrt.transportgzm.pl:5443/gtfsrt/gzm	Override the base URL
GZM_HTTP_TIMEOUT	10	HTTP timeout in seconds
GZM_CACHE_TTL	10	In-process feed cache TTL in seconds
GZM_MAX_VEHICLES	200	Default cap for vehicles()
GZM_MAX_TRIPS	200	Default cap for trip_updates()
GZM_MAX_ALERTS	100	Default cap for alerts()
GZM_USER_AGENT	transport-gzm-mcp/0.1 (+https://github.com/Wiktor102/transport-gzm)	Outgoing UA
LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR

License

MIT. GTFS-RT data © Górnośląsko-Zagłębiowska Metropolia, CC-BY 4.0.