Skip to main content
Glama
TfNSW Trip Planner MCP Server

TfNSW Trip Planner MCP Server

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

/mcp

Streamable HTTP transport — use this

/sse, /messages/

Legacy SSE transport, for clients that need it

/health

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 stdio

Claude 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 stdio

Claude 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

find_stop

Search stops, wharves, POIs and addresses by name

find_stop_by_id

Look up one stop by its numeric ID

best_stop

Return only the single best-matching location for a name

plan_trip

Plan a journey between two place names or stop IDs

plan_trip_from_coordinate

Plan a journey starting from a GPS coordinate

plan_cycling_trip

Plan a cycling route, optionally mixed with transit

get_departures

Live departure board for a stop or platform

get_alerts

Service alerts: disruptions, trackwork, planned changes

find_nearby

Stops and POIs near a coordinate, with distances

get_vehicle_positions

Live GPS positions of vehicles on a network

Notes:

  • Times. Tools taking a when accept 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_departures is 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 needs tfnsw-trip-planner 1.5.0, the minimum this server depends on.)

  • Capped results. get_alerts, find_nearby and get_vehicle_positions can 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 a max_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_trip accepts origin/destination as free text ("100 Harris Street Pyrmont", "Bondi Junction") and resolves them server-side, so a model does not spend two best_stop round trips before planning can start. Pass origin_id/destination_id instead 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_type defaults to "any", not "stop". An address resolves to a streetID:... ID of type singlehouse, and planning it with type_origin=stop returned zero journeys — verified against the live API. The old "stop" default silently failed every address-to-address trip. (Since tfnsw-trip-planner 1.5.0 it fails loudly instead, with "stop invalid".)

  • Journey detail. The journey tools take a detail level, 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.

    detail

    includes

    real Pyrmont → Engadine trip

    answer

    totals 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. full only fits when paired with max_results of 1–3.

  • Concise results. get_departures, get_alerts and find_nearby default to concise=true, returning only the fields a model reads. Pass concise=false for every field. Each result reports concise, so a model can see it was trimmed.

    Tool

    concise fields

    real response, full → concise

    get_departures

    departure_planned, departure_estimated, transportation.name/number

    Circular Quay, 40 departures: 39.7 → 7.8 KB

    get_alerts

    subtitle, url, last_modification, affected_lines, affected_stops

    Central (stop_id=200060): 56.8 → 2.4 KB

    find_nearby

    name, kind, distance, id

    Central, 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_estimated is null when there is no live data.

    In concise alerts, affected_lines and affected_stops are 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, kind is the TfNSW draw class (StopPoint, StopArea, EntryExit, Bench, …), because the raw type is unknown on every result and most results have no name. id appears only on stops, taken from the stop ID TfNSW puts in properties.description. Every raw id is a coord:... string that no other tool accepts.

  • Legs are built from an allowlist, not by dropping known-bad fields. The old blocklist removed coords and stop_sequence and passed everything else through, including the raw upstream properties bag — 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 transportation block 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_stop takes limit, not max_results — deliberately a different name, because it bounds the upstream query rather than truncating a fetched list, so count is exact and no bandwidth is wasted.

  • get_vehicle_positions reads the GTFS-Realtime feed, which is a separate product on the Open Data portal — your key must be subscribed to it as well. An unrecognised mode is rejected with the list of valid feeds rather than being passed through to an opaque upstream 404. The nine valid feeds are buses, sydneytrains, metro, nswtrains, ferries/sydneyferries, lightrail/cbdandsoutheast, lightrail/innerwest, lightrail/newcastle and lightrail/parramatta.

    The list is taken from the library rather than restated here, so the two cannot drift. TfNSW serves sydneytrains and lightrail/innerwest from a v2 endpoint and the rest from v1; tfnsw-trip-planner routes 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 -d
curl -sf localhost:6401/health

See DEPLOYMENT.md for the Coolify setup.

Local development

uv sync
uv 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 stdio

See 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 pytest

Smoke tests against the real API are opt-in and skipped unless a key is present:

TFNSW_API_KEY=your_key uv run pytest -m live

CI

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

server.py

The 10 tools and their argument mapping

auth.py

X-API-Key extraction (or TFNSW_API_KEY under stdio) and per-call client lifecycle

serialization.py

Library dataclasses → JSON-safe structures

app.py

ASGI app wiring both transports plus /health

__main__.py

CLI entry point: --transport http (default) or stdio

TfNSW Trip Planner MCP Server MCP server – quality and maintenance score on Glama

Available Tools

10 tools
best_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

    A4.1/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      This 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 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT