UK Bus Departures MCP Server

An MCP (Model Context Protocol) server for UK bus departures and nearby bus stop discovery.

Features

• 🚌 Real-time bus departure information for UK stops via bustimes.org

• 📍 Nearby bus stop lookup from a place name or coordinates

• 🔍 ATCO code validation

• ⚡ Built-in caching and respectful rate limiting

• 🗄️ Cloudflare D1-backed local stop lookup using NaPTAN

• 🌐 Cloudflare Workers compatible

Tools

get_bus_departures

Fetches real-time bus departures for a UK bus stop.

Parameters

• stop_code (string): UK bus stop ATCO code

• date (optional string): YYYY-MM-DD

• time (optional string): HH:MM

Example

{
  "tool": "get_bus_departures",
  "arguments": {
    "stop_code": "0100BRP90023"
  }
}

find_nearby_bus_stops

Finds the nearest active UK bus stops and their ATCO codes.

Provide either:

• query for free-text search such as "Ada Lovelace Building" or a postcode

• or latitude and longitude

Optional parameters:

• radius_m default 750, max 5000

• limit default 5, max 10

Example: free-text

{
  "tool": "find_nearby_bus_stops",
  "arguments": {
    "query": "Ada Lovelace Building",
    "limit": 5
  }
}

Example: coordinates

{
  "tool": "find_nearby_bus_stops",
  "arguments": {
    "latitude": 51.4545,
    "longitude": -2.5879,
    "radius_m": 1000
  }
}

Response shape

{
  "resolved_location": {
    "name": "Ada Lovelace Building, Upper Richardson, Tithebarn, Broadclyst, Exeter, Devon, EX5 2FN, United Kingdom",
    "latitude": 50.7330647,
    "longitude": -3.4595234,
    "source": "nominatim"
  },
  "alternatives": [],
  "used_radius_m": 750,
  "expanded_search": false,
  "stops": [
    {
      "atco_code": "0100BRP90311",
      "naptan_code": "bstgwpm",
      "stop_name": "Temple Meads Stn",
      "indicator": "T7",
      "locality_name": "Temple Meads",
      "distance_m": 184,
      "latitude": 51.45014,
      "longitude": -2.5856
    }
  ]
}

validate_atco_code

Validates an ATCO code format and returns stop metadata if valid.

D1 Setup

find_nearby_bus_stops requires a D1 database bound as bustimes_mcp_db.

1. Create the database:

bunx wrangler d1 create bustimes-mcp-db

2. The repo is already configured with your database_id in wrangler.jsonc.

3. Apply migrations locally:

npm run d1:migrate:local

4. Apply migrations remotely:

npm run d1:migrate:remote

5. Import NaPTAN bus stops locally:

npm run import:naptan -- --database bustimes_mcp_db --local

6. Import NaPTAN bus stops remotely:

npm run import:naptan -- --database bustimes_mcp_db --remote

The import script downloads the national NaPTAN CSV, filters to active bus stops, and loads them into the stops table.

Development

Prerequisites

• Node.js 18+

• Wrangler CLI

Local Development

npm install
npm run d1:migrate:local
npm run import:naptan -- --database bustimes_mcp_db --local
npm run dev

Deployment

npm run deploy

Type Checking

npm run type-check

Connect to Claude Desktop

{
  "mcpServers": {
    "uk-bus-departures": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

Technical Details

Data Sources

• bustimes.org API: stop metadata

• bustimes.org HTML: real-time departures via scraping

• NaPTAN: UK stop index used for nearby stop lookup

• Nominatim: free-text geocoding for place-name search

Nearby Stop Lookup

• NaPTAN data is loaded into D1 and queried locally at runtime

• Free-text location search is resolved with Nominatim and cached in D1 for 30 days

• Nearby stop lookup uses a bounding-box SQL prefilter and Haversine distance sorting

• If no stops are found within the requested radius and the radius is below 2000m, the search expands once to 2000m

Rate Limiting and Caching

• 2-second delay between bustimes.org requests

• 5-minute in-memory cache for bustimes stop metadata

• 30-day D1 cache for Nominatim geocoding results

Nominatim Notes

• This integration is for end-user-triggered lookups only

• Do not use it for autocomplete or background/systematic geocoding

• The server sends a custom User-Agent and caches results

• If you surface geocoded results to end users, include OpenStreetMap attribution where appropriate

Limitations

• UK only: text geocoding is constrained to Great Britain

• Nearby stops require D1: the tool will fail until the D1 binding is configured, migrated, and populated

• HTML dependency: departures scraping is fragile to bustimes.org layout changes

• Geocoding ambiguity: building names can resolve to multiple plausible matches; alternatives are returned for inspection

• No combined departures-by-nearby-stop tool: v1 stops at discovery of nearby stops and ATCO codes

License

MIT License

Disclaimer

This server uses public data from bustimes.org, NaPTAN, and OpenStreetMap/Nominatim. Use responsibly and respect each upstream service's terms and usage policies.