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:

Response:

validate_atco_code

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

Parameters:

• stop_code (string): ATCO code to validate

Response:

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

Deployment

Type Checking

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:

1. Follow Anthropic's Quickstart

2. In Claude Desktop go to Settings > Developer > Edit Config

3. Update with this configuration:

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.