TfNSW Trip Planner MCP Server
This MCP server exposes Transport for NSW trip-planning data and live transport information to LLM clients.
Search stops, stations, wharves, POIs and addresses by name, or look up a stop by ID.
Find the single best-matching stop for a place name.
Plan public transport trips between place names or stop IDs, including coordinate-origin trips.
Plan cycling routes, optionally mixed with public transport.
Get live departure boards for stops or platforms.
Retrieve service alerts, disruptions, trackwork and planned changes.
Find nearby stops and POIs around a GPS coordinate with distances.
Fetch live GPS positions for buses, trains, metro, ferries and light rail feeds.
Control response size and detail with limits, capped results, concise/full output and journey detail levels.
Supply the TfNSW API key per request over HTTP or via environment variable over stdio.
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., "@TfNSW Trip Planner MCP Server Plan a trip from Central Station to Circular Quay at 5pm"
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.
TfNSW Trip Planner MCP Server
An MCP server exposing the
Transport for NSW trip planning APIs to
LLM clients, built on the
tfnsw-trip-planner library.
Ten tools cover stop search, journey planning, live departure boards, service alerts, nearby-stop lookup and live vehicle positions.
Authentication
The server stores no credentials. Every caller supplies their own TfNSW Open Data API key on every request:
X-API-Key: <your TfNSW API key>Get a free key from the TfNSW Open Data portal.
A request without the header gets an error naming the header rather than a
silent failure. apikey <key> and Bearer <key> forms are accepted too, since
TfNSW's own docs use the former.
Each tool call builds a client from that request's key and discards it when the call returns, so one caller's key is never reused for another's request.
Over stdio (see Running locally over stdio)
there are no headers: the server is spawned by a single local client, which
passes its key in the TFNSW_API_KEY environment variable instead. That variable
is read only in stdio mode — an HTTP deployment ignores it, so it can never end
up serving a key of its own to remote callers.
HTTP connections are nevertheless pooled process-wide, which cuts roughly
93ms — a TCP and TLS handshake — off every call. The split is deliberate: a
connection pool is keyed by host, not by credential, so it can be shared safely,
whereas the library writes the API key into session.headers and a shared
session would let one caller's key overwrite another's mid-flight.
Related MCP server: PTV Transit MCP Server
Endpoints
Path | Purpose |
| Streamable HTTP transport — use this |
| Legacy SSE transport, for clients that need it |
| Unauthenticated liveness probe |
| Service description |
Listens on 0.0.0.0:6401; override with the HOST and PORT environment
variables.
Connecting a client
Running locally over stdio (uvx)
No hosted server needed: an MCP client can spawn the server itself with
uvx and talk to it over stdio. The
key goes in TFNSW_API_KEY.
uvx --from git+https://github.com/maxim75/tfnsw_trip_planner_mcp tfnsw-trip-planner-mcp --transport stdioClaude Code:
claude mcp add tfnsw --env TFNSW_API_KEY=YOUR_KEY -- uvx --from git+https://github.com/maxim75/tfnsw_trip_planner_mcp tfnsw-trip-planner-mcp --transport stdioClaude Desktop (or any client with a JSON mcpServers config):
{
"mcpServers": {
"tfnsw": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/maxim75/tfnsw_trip_planner_mcp",
"tfnsw-trip-planner-mcp", "--transport", "stdio"
],
"env": { "TFNSW_API_KEY": "YOUR_KEY" }
}
}
}From a local checkout, use --from /path/to/tfnsw_trip_planner_mcp instead.
MCP_TRANSPORT=stdio works in place of --transport stdio. Without
TFNSW_API_KEY the server still starts and answers initialize/tools/list,
but every tool call returns an error naming the variable.
Claude Code (hosted server)
Header support is built in:
claude mcp add --transport http tfnsw https://your-host/mcp --header "X-API-Key: YOUR_KEY"Claude Desktop (hosted server)
Claude Desktop's (and claude.ai's) native "Add custom connector" UI accepts a
URL and OAuth credentials only — it has no field for a custom header, so it
cannot be used with this server. Connect through the
mcp-remote bridge instead (needs Node):
{
"mcpServers": {
"tfnsw": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-host/mcp",
"--transport", "http-only",
"--header", "X-API-Key:${TFNSW_KEY}"
],
"env": { "TFNSW_KEY": "YOUR_KEY" }
}
}
}mcp-remote needs Name:value with no space after the colon. Config lives at
~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or
%APPDATA%\Claude\claude_desktop_config.json on Windows. Restart the app after
editing.
For a client that only speaks the older transport, point it at /sse and pass
--transport sse-only.
Tools
plan_trip takes plain place names and resolves them itself. The other tools
are addressed by numeric stop ID, so resolve a name with find_stop or
best_stop first and pass the ID onwards.
Tool | What it does |
| Search stops, wharves, POIs and addresses by name |
| Look up one stop by its numeric ID |
| Return only the single best-matching location for a name |
| Plan a journey between two place names or stop IDs |
| Plan a journey starting from a GPS coordinate |
| Plan a cycling route, optionally mixed with transit |
| Live departure board for a stop or platform |
| Service alerts: disruptions, trackwork, planned changes |
| Stops and POIs near a coordinate, with distances |
| Live GPS positions of vehicles on a network |
Notes:
Times. Tools taking a
whenaccept ISO 8601, e.g.2026-08-30T09:15. Without an offset the value is Australia/Sydney local time. An unparseable value is rejected rather than ignored.Errors. A failed call is a tool error carrying TfNSW's own message. That includes the errors the trip planner reports inside an HTTP 200, such as an invalid origin or destination ID: those are errors now, not an empty result. "No route found" is still an empty list.
get_departuresis unchanged: TfNSW answers an unknown stop ID with an empty board, not an error. Network errors and HTTP 429/502/503/504 are retried twice with backoff before failing; a rate limit that outlasts the retries is reported as one, with the wait TfNSW asked for, so a model backs off instead of retrying into the same quota. (All of this needstfnsw-trip-planner1.5.0, the minimum this server depends on.)Capped results.
get_alerts,find_nearbyandget_vehicle_positionscan each answer with far more than a caller can use — an unfiltered alert fetch returns every alert in NSW (~280, 1.3MB of JSON), and a 500m nearby search can return 600+ locations. They take amax_results(20, 50 and 100 respectively), constrained to>= 1.This is not only about context budget: MCP sends each result twice (as text content and as structured content) and clients cap a single SSE event at 1MiB, so an oversized reply fails outright with "SSE stream ended without a response".
Place names.
plan_tripacceptsorigin/destinationas free text ("100 Harris Street Pyrmont", "Bondi Junction") and resolves them server-side, so a model does not spend twobest_stopround trips before planning can start. Passorigin_id/destination_idinstead when you already hold an ID — giving both for the same end is an error rather than a silent preference. A resolved result echoes what each name matched:{"origin": {"id": "...", "name": "100 Harris St, Pyrmont"}}Resolution refuses a weak match rather than guessing. TfNSW's stop finder practically never returns nothing — it returns its nearest guess with a score, and
"Zzzqqxnowhere Placeton"really does resolve to Iceton Pl, Yass. Measured on the live API, real places score 250 (street addresses) to 996 (stations) while nonsense scores 47–154, so anything under 200 is rejected with an error naming the candidate it declined to use.origin_typedefaults to"any", not"stop". An address resolves to astreetID:...ID of typesinglehouse, and planning it withtype_origin=stopreturned zero journeys — verified against the live API. The old"stop"default silently failed every address-to-address trip. (Sincetfnsw-trip-planner1.5.0 it fails loudly instead, with "stop invalid".)Journey detail. The journey tools take a
detaillevel, because the raw response is overwhelmingly data a model never reads. Journey totals (departure,arrival,duration_min,changes,via) are always present, so the commonest questions need no leg data at all.detailincludes
real Pyrmont → Engadine trip
answertotals only
1.4 KB
summary(default)+ legs: times, route, platform, alerts
11.4 KB
stops+ intermediate stop names
—
full+ route polyline
—
Every result reports the level it used, so a model can see it was trimmed and ask for more rather than assuming the data does not exist.
fullonly fits when paired withmax_resultsof 1–3.Concise results.
get_departures,get_alertsandfind_nearbydefault toconcise=true, returning only the fields a model reads. Passconcise=falsefor every field. Each result reportsconcise, so a model can see it was trimmed.Tool
concise fields
real response, full → concise
get_departuresdeparture_planned,departure_estimated,transportation.name/numberCircular Quay, 40 departures: 39.7 → 7.8 KB
get_alertssubtitle,url,last_modification,affected_lines,affected_stopsCentral (
stop_id=200060): 56.8 → 2.4 KBfind_nearbyname,kind,distance,idCentral, 500 m, 50 results: 18.9 → 2.8 KB
{"departure_planned": "2026-09-29T17:24:00+10:00", "departure_estimated": "2026-09-29T17:25:06+10:00", "transportation": {"name": "Sydney Buses Network 333", "number": "333"}}departure_estimatedisnullwhen there is no live data.In concise alerts,
affected_linesandaffected_stopsare deduplicated lists of line numbers and stop names. Full, each affected line is a whole object, and trip-level alerts embed the trip's timetable. One Central alert lists 163 lines, which made a single-stop fetch larger than a network-wide one.In concise nearby results,
kindis the TfNSW draw class (StopPoint,StopArea,EntryExit,Bench, …), because the rawtypeisunknownon every result and most results have no name.idappears only on stops, taken from the stop ID TfNSW puts inproperties.description. Every rawidis acoord:...string that no other tool accepts.Legs are built from an allowlist, not by dropping known-bad fields. The old blocklist removed
coordsandstop_sequenceand passed everything else through, including the raw upstreampropertiesbag — lift equipment heights,AREA_NIVEAU_DIVA,areaGid,pbyb, and the platform name repeated under three separate keys. On a real trip that passthrough was 28% of the payload. An allowlist cannot regress that way when TfNSW adds a field. Also:the four planned/estimated time fields collapse to the time that will actually happen, plus
scheduled_*only when there is a real delay (20 of 22 timed stops on a real trip had the two exactly equal);null times, empty alert lists and the empty
transportationblock that every walking leg carries are omitted rather than serialized;stop IDs are echoed for chaining only when they are real stop IDs, not 129-byte composite
streetID:...blobs that no other tool accepts.
Together with the resolution above, the question "when do I arrive at 32 Geelong Rd if I leave now from 100 Harris Street Pyrmont" went from 3 calls and ~10,800 tokens to 1 call and ~356 tokens (
detail="answer").find_stoptakeslimit, notmax_results— deliberately a different name, because it bounds the upstream query rather than truncating a fetched list, socountis exact and no bandwidth is wasted.get_vehicle_positionsreads the GTFS-Realtime feed, which is a separate product on the Open Data portal — your key must be subscribed to it as well. An unrecognisedmodeis rejected with the list of valid feeds rather than being passed through to an opaque upstream 404. The nine valid feeds arebuses,sydneytrains,metro,nswtrains,ferries/sydneyferries,lightrail/cbdandsoutheast,lightrail/innerwest,lightrail/newcastleandlightrail/parramatta.The list is taken from the library rather than restated here, so the two cannot drift. TfNSW serves
sydneytrainsandlightrail/innerwestfrom a v2 endpoint and the rest from v1;tfnsw-trip-plannerroutes each feed to the version that actually serves it (since 1.4.0).
Results are returned as structured JSON. Every list-returning tool answers with
the same shape, so returned is always present and count is always the true
total before any capping:
{"count": 618, "returned": 50, "locations": [...]}Single lookups (find_stop_by_id, best_stop) return {"location": {...}},
or {"location": null} when nothing matches.
Running it
Docker (how it is deployed)
docker compose up --build -dcurl -sf localhost:6401/healthSee DEPLOYMENT.md for the Coolify setup.
Local development
uv syncuv run python -m tfnsw_trip_planner_mcp--host and --port override HOST and PORT; --help lists every option.
Stdio
TFNSW_API_KEY=your_key uv run tfnsw-trip-planner-mcp --transport stdioSee Running locally over stdio for client
configs. Directory scanners that spawn the container speak stdio too; they need
no key, since they only check the initialize/tools/list handshake. Run the
image that way with -e MCP_TRANSPORT=stdio. The default deployment above
(Docker/Coolify, /mcp and /sse) is unaffected.
Tests
The default suite is fully offline — the library client is mocked, so no key is needed and no request leaves the machine:
uv run pytestSmoke tests against the real API are opt-in and skipped unless a key is present:
TFNSW_API_KEY=your_key uv run pytest -m liveCI
GitHub Actions runs on every push and pull request: ruff, the offline suite,
and a Docker job that builds the image, waits for /health, and checks the
running container lists all 10 tools.
The live tests run on main and on manual dispatch. They skip themselves
unless a TFNSW_API_KEY repository secret exists, so CI is green without one —
add it under Settings → Secrets and variables → Actions to enable them. Fork
pull requests never receive the secret, so they always skip.
Layout
File | Role |
| The 10 tools and their argument mapping |
|
|
| Library dataclasses → JSON-safe structures |
| ASGI app wiring both transports plus |
| CLI entry point: |
Available Tools
10 toolsbest_stopA
Return only the single best-matching location for a name.
A shortcut for find_stop when you just need one stop ID and do not want to
weigh alternatives. Returns `{"location": null}` if nothing matches.
Args:
query: The place name to resolve, e.g. "Bondi Junction".
Inputs: query (required). Returns: object
find_nearbyA
Find stops and points of interest near a GPS coordinate.
Each result carries its distance in metres from the coordinate. A dense area
can return hundreds of locations within 500m, so results are capped:
`count` is the true total and `returned` is how many are included. Narrow
`radius_m` rather than raising `max_results` to get more relevant results.
Args:
latitude: Latitude in decimal degrees, e.g. -33.8613.
longitude: Longitude in decimal degrees, e.g. 151.2107.
radius_m: Search radius in metres.
type_1: TfNSW result category. "GIS_POINT" covers stops and POIs.
draw_class: Optional TfNSW sub-category filter.
max_results: Maximum locations to return.
Inputs: latitude (required), longitude (required), type_1, radius_m, +2 more. Returns: object
find_stopA
Search for stops, stations, wharves, points of interest and addresses by name.
Use this to turn a place name into the stop ID that the trip planning and
departure tools require.
Args:
query: What to search for, e.g. "Circular Quay" or "Town Hall Station".
location_type: Restrict results — "any", "stop", "platform", "poi",
"address", "street" or "locality".
limit: Ask the TfNSW API to return at most this many matches. Unlike
max_results on the capped tools, this bounds the upstream query
rather than truncating a fetched list, so `count` is exact.
Inputs: query (required), limit, location_type. Returns: object
find_stop_by_idA
Look up a single stop by its numeric TfNSW stop ID.
Returns `{"location": null}` if no stop carries that ID.
Args:
stop_id: The stop ID, e.g. "10101331".
Inputs: stop_id (required). Returns: object
get_alertsA
Retrieve service alerts: disruptions, trackwork and planned changes.
Pass a stop_id whenever you can. A network-wide fetch returns every alert in
NSW — hundreds of them — so results are capped: `count` is the true total
and `returned` is how many are included.
Args:
when: Optional ISO 8601 date/time to check alerts for; Sydney local time
if no offset given. Defaults to now.
stop_id: Restrict to alerts affecting one stop. Omit for network-wide.
current_only: Only alerts in effect now. Set false to include future ones.
max_results: Maximum alerts to return.
Inputs: when, stop_id, max_results, current_only. Returns: object
get_departuresA
List upcoming departures from a stop — the live departure board.
Args:
stop_id: Stop ID to read departures for. Resolve names with find_stop.
when: Optional ISO 8601 date/time to board from; Sydney local time if no
offset given. Defaults to now.
platform_id: Restrict to a single platform or stand.
realtime: Include live delay information alongside scheduled times.
Inputs: stop_id (required), when, realtime, platform_id. Returns: object
get_vehicle_positionsA
Fetch live GPS positions of vehicles currently running on a network.
Unlike the other tools, which return timing estimates, this returns where
each vehicle physically is. Note this feed is a separate product on the
TfNSW Open Data portal — your API key must be subscribed to it as well.
Feeds can carry thousands of vehicles, so results are capped: `count` is the
true feed size and `returned` is how many are included.
Args:
mode: Which feed to read. One of "buses", "sydneytrains", "metro",
"nswtrains", "ferries/sydneyferries", "lightrail/cbdandsoutheast",
"lightrail/innerwest", "lightrail/newcastle",
"lightrail/parramatta".
max_results: Maximum vehicles to return.
Inputs: mode (required), max_results. Returns: object
plan_cycling_tripA
Plan a cycling route, optionally combined with public transport.
Args:
origin_id: Stop ID to start from.
destination_id: Stop ID to finish at.
profile: Route preference — "EASIER" (gentler gradients and quieter
roads), "MODERATE", or "MORE_DIRECT" (fastest, busier roads).
when: Optional ISO 8601 date/time; Sydney local time if no offset given.
bike_only: Cycle the whole way. Set false to allow mixed bike + transit.
max_time_minutes: Reject routes longer than this.
cycle_speed: Assumed cycling speed in km/h.
detail: How much to return per journey. "answer" gives only departure,
arrival, duration, changes and the mode summary — use it for "when
do I get there" and "how long does it take", which is most questions.
"summary" (default) adds the legs, each with its times, route,
platform and any alerts. "stops" adds intermediate stop names.
"full" adds the map polyline and is very large — pair it with
max_results=1 or 2 or the call may exceed the client's size limit.
max_results: Maximum journeys to return.
Inputs: origin_id (required), destination_id (required), when, detail, +5 more. Returns: object
plan_tripA
Plan a public transport journey between two places.
Prefer passing plain place names as `origin` and `destination` — addresses,
stations, suburbs and landmarks all work, and the server resolves them
itself. You do NOT need to call find_stop or best_stop first; doing so costs
two extra round trips for no benefit. Use `origin_id`/`destination_id` only
when you already hold a stop ID from an earlier call.
Args:
origin: Place to depart from, e.g. "100 Harris Street Pyrmont" or
"Circular Quay". Resolved server-side.
destination: Place to arrive at, e.g. "32 Geelong Rd Engadine".
origin_id: Stop ID to depart from. Alternative to `origin`, not both.
destination_id: Stop ID to arrive at. Alternative to `destination`.
when: Optional ISO 8601 date/time, e.g. "2026-08-30T09:15". Without an
offset this is Sydney local time. Defaults to now.
arrive_by: Treat `when` as the desired arrival time instead of departure.
origin_type: Kind of the origin ID. Leave as "any", which resolves stops,
addresses and POIs alike; "stop" rejects address IDs and returns
nothing for them.
destination_type: Kind of the destination ID. Leave as "any".
realtime: Include live delay information.
wheelchair: Return only wheelchair-accessible journeys.
detail: How much to return per journey. "answer" gives only departure,
arrival, duration, changes and the mode summary — use it for "when
do I get there" and "how long does it take", which is most questions.
"summary" (default) adds the legs, each with its times, route,
platform and any alerts. "stops" adds intermediate stop names.
"full" adds the map polyline and is very large — pair it with
max_results=1 or 2 or the call may exceed the client's size limit.
max_results: Maximum journeys to return.
Inputs: when, detail, origin, realtime, +8 more. Returns: object
plan_trip_from_coordinateA
Plan a journey starting from a GPS coordinate rather than a stop.
Use this when the starting point is a user's current location or an
arbitrary address, and only the destination is a known stop.
Args:
latitude: Starting latitude in decimal degrees, e.g. -33.8613.
longitude: Starting longitude in decimal degrees, e.g. 151.2107.
destination_id: Stop ID to arrive at.
when: Optional ISO 8601 date/time; Sydney local time if no offset given.
arrive_by: Treat `when` as the desired arrival time.
realtime: Include live delay information.
wheelchair: Return only wheelchair-accessible journeys.
detail: How much to return per journey. "answer" gives only departure,
arrival, duration, changes and the mode summary — use it for "when
do I get there" and "how long does it take", which is most questions.
"summary" (default) adds the legs, each with its times, route,
platform and any alerts. "stops" adds intermediate stop names.
"full" adds the map polyline and is very large — pair it with
max_results=1 or 2 or the call may exceed the client's size limit.
max_results: Maximum journeys to return.
Inputs: latitude (required), longitude (required), destination_id (required), when, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target clearly separate actions: searching stops, planning trips, departures, alerts, and vehicle positions. The main ambiguity is best_stop, which largely duplicates find_stop in shortcut form, and plan_trip_from_coordinate overlaps somewhat with plan_trip, though the descriptions clarify the intended input types.
Tool names generally follow a verb_noun pattern: find_stop, plan_trip, get_departures, get_alerts, find_nearby. The one outlier is best_stop, which uses an adjective instead of a verb, and plan_trip_from_coordinate / plan_cycling_trip are longer but still consistent in style.
Ten tools is a well-scoped size for a transit trip planning server. Each tool addresses a distinct need—stop resolution, journey planning, departures, alerts, vehicle positions, cycling, and nearby search—without redundancy or bloat.
The server covers the core domain well: stop lookup, trip planning, departures, alerts, vehicle positions, and nearby discovery. Minor gaps exist, such as no coordinate-to-coordinate trip planning or detailed route/stop schedule exploration, but agents can accomplish most user journeys with the available tools.
Related MCP Connectors
Transport for NSW MCP — journey planning, live departures, service alerts and commuter car-park…
Transport for London (TfL) Unified API MCP — keyless.
Read-only public transit departures, stop search, and city coverage for bus and train users.
Travel disruption signals and exposure checks. Needs an account: OAuth sign-in or an API key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThis server enables large language models to access and interact with real-time transport alerts from Transport for NSW's network, supporting filtering by transport mode and returning formatted alert information about disruptions and planned works.13 npm7MIT
- AlicenseAqualityDmaintenanceExposes Victoria's public transport (PTV) GTFS timetable data as MCP tools, allowing LLMs to answer natural-language questions about routes, stops, and departure times.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to query live Transport for London data, including service status, arrivals, journey planning, bike points, crowding, and fares.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables journey planning, live departures, service alerts, and commuter car-park occupancy for Sydney and New South Wales across trains, metro, buses, ferries, and light rail, accessible via natural language queries.67 npmMIT