UK Bus Departures MCP Server

An MCP (Model Context Protocol) server that provides real-time UK bus departure information by scraping bustimes.org.

Features

🚌 Real-time bus departure information for UK stops
🔍 ATCO code validation
⚡ Built-in caching and rate limiting
🌐 Cloudflare Workers compatible
📊 Structured JSON responses

Usage

This MCP server provides the following tools:

`get_bus_departures`

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

Parameters:

stop_code (string): UK bus stop ATCO code (e.g., '0100BRP90023')

Example:

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

Response:

{
  "departures": [
    {
      "service_number": "75",
      "destination": "Hengrove Park",
      "scheduled_time": "15:02",
      "expected_time": "15:14"
    }
  ],
  "stop_name": "Bishopston Sommerville Road (S-bound)",
  "stop_code": "0100BRP90023",
  "location": [-2.59102, 51.47324],
  "last_updated": "2025-09-13T14:28:00.000Z"
}

`validate_atco_code`

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

Parameters:

stop_code (string): ATCO code to validate

Response:

{
  "stop_code": "0100BRP90023",
  "is_valid": true,
  "metadata": {
    "name": "Bishopston Sommerville Road",
    "common_name": "Sommerville Road",
    "long_name": "Bishopston Sommerville Road (S-bound)",
    "location": [-2.59102, 51.47324],
    "indicator": "S-bound",
    "bearing": "S",
    "active": true
  }
}

ATCO Codes

UK bus stops use ATCO (Association of Transport Coordinating Officers) codes with the format:

13 characters: NNNNAAANNNNN[A]
4 digits + 3 letters + 5 digits + optional letter
Example: 0100BRP90023

Rate Limiting

The server implements:

2-second delay between requests to bustimes.org
5-minute caching for stop metadata (departures are always fresh)
Respectful scraping practices

Development

Prerequisites

Node.js 18+
Wrangler CLI

Local Development

npm install
npm run dev

Deployment

npm run deploy

Type Checking

npm run type-check

API Endpoints

When deployed as a Cloudflare Worker:

GET /mcp - MCP protocol endpoint
GET /sse - Server-Sent Events endpoint

Connect to Claude Desktop

To connect this MCP server to Claude Desktop:

Follow Anthropic's Quickstart
In Claude Desktop go to Settings > Developer > Edit Config
Update with this configuration:

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

For deployed version, replace localhost URL with your Workers domain.

Technical Details

Data Sources

bustimes.org API: Stop metadata (names, coordinates, etc.)
bustimes.org HTML: Real-time departure information via scraping

Architecture

Parser: Robust HTML parsing with multiple fallback strategies
Service: HTTP client with rate limiting and caching
Models: Type-safe data structures using Zod schemas

Error Handling

Invalid ATCO codes (format validation)
Missing bus stops (404 responses)
Network timeouts and failures
HTML structure changes

Limitations

UK Only: Limited to UK bus stops with ATCO codes
HTML Dependency: Fragile to website structure changes
Rate Limited: 2-second delays between requests
No Historical Data: Real-time and scheduled data only

License

MIT License

Disclaimer

This server scrapes public data from bustimes.org for informational purposes. Please use responsibly and respect the website's terms of service.

UK Bus Departures MCP Server