Skip to main content
Glama
Melbourne PTV MCP Server

Melbourne PTV MCP Server

by vchandwani
README.md
# Melbourne PTV MCP Server

MCP server for Melbourne public transport, using the PTV Timetable API v3.

## Tools
- `search_stops` – find stop IDs by name
- `stops_nearby` – stops near a lat/long
- `get_departures` – next departures from a stop (real-time where available)
- `get_disruptions` – current or planned disruptions
- `leave_now_or_wait` – when to leave home, given walk time, delays and disruptions

## Setup
1. Request a PTV developer ID and API key from PTV (see their Timetable API page).
2. Build: `npm install && npm run build`
3. Add to Claude Desktop config (Settings > Developer > Edit config):

```json
{
  "mcpServers": {
    "ptv": {
      "command": "node",
      "args": ["/absolute/path/to/ptv-mcp/dist/index.js"],
      "env": { "PTV_DEV_ID": "your_id", "PTV_API_KEY": "your_key" }
    }
  }
}
```

Claude Code: `claude mcp add ptv -e PTV_DEV_ID=... -e PTV_API_KEY=... -- node /absolute/path/to/ptv-mcp/dist/index.js`

## Demo mode (no API key needed)
Set `PTV_DEMO=true` instead of the PTV credentials to get fictional sample data in the same format.
Useful for trying the tools, demos and development. Responses are labelled as demo data.

Claude Code: `claude mcp add ptv-demo -e PTV_DEMO=true -- node /absolute/path/to/ptv-mcp/dist/index.js`

## Attribution
Data from Public Transport Victoria, licensed under Creative Commons Attribution 3.0 Australia.

## Licence
MIT

## Leave-time alerts (optional watcher)
MCP is request/response, so Claude can't push notifications. `ptv-watch` is a separate small
program that polls PTV and sends a notification via [ntfy.sh](https://ntfy.sh) (free) when your
leave time shifts or a new disruption appears.

```
export PTV_DEV_ID=... PTV_API_KEY=... NTFY_TOPIC=some-long-random-string
node dist/watch.js --mode train --stop <stop_id> --walk 8 [--route <id>] [--every 120] [--threshold 3]
```
Install the ntfy app on your phone and subscribe to the same topic.