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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues