# Transport for London MCP Server

⚠️ **Important Disclaimer**: This is not an official Transport for London (TfL) MCP server. This is an independent project that uses the publicly available TfL Unified API to provide transport data. It is not affiliated with, endorsed by, or officially supported by Transport for London.

A Model Context Protocol (MCP) server providing real-time Transport for London data, including line status, journey planning, and disruption information. This server is deployed on Cloudflare Workers and can be used with any MCP-compatible client like Claude Desktop.

## Demo

### With MCP-UI Support
Experience interactive visual cards and UI components with MCP-UI compatible clients (shown here using nanobot.ai):

![Demo with MCP-UI](assets/demo-with-mcp-ui.gif)

### Without MCP-UI
For clients without MCP-UI support, the server returns JSON data:

![Demo without MCP-UI](assets/demo.gif)

## Features

This MCP server provides the following tools:

### 🎯 **show_line_status_selector** (NEW!)
Display an interactive selector with buttons for all TfL lines. This uses MCP-UI's externalUrl feature to load an interactive HTML interface in your MCP client.
- **Parameters:** None
- **Output:** 
  - An interactive UI with clickable buttons for all available TfL lines (Victoria, Central, Northern, Piccadilly, Jubilee, Bakerloo, Circle, District, Hammersmith & City, Metropolitan, Waterloo & City, Elizabeth, DLR, Overground, and Tram)
  - Each button is styled with the official line color
  - Clicking a button automatically calls `get_line_status` for that line
  - Perfect for quickly checking status across multiple lines

**Use Case Example:**
Ask "Show me the line status selector" or "Show status" to get an interactive view of all lines. Click any line button to instantly check its current status.

### 🚇 **get_line_status**
Get the current status of a specific TfL transport line with beautiful visual cards (MCP-UI support).
- **Parameters:**
  - `lineId`: The line ID to query (e.g., 'central', 'piccadilly', 'northern', 'victoria')
- **Output:** Returns both JSON data and a visual UI card with TfL branding, line colors, and status badges

#### MCP-UI Visual Responses

When used with MCP-UI compatible clients (like Claude Desktop with MCP-UI support), the server returns beautiful visual cards:

**Good Service:**

![Victoria Line - Good Service](https://github.com/user-attachments/assets/1b36fa00-a5a9-4a84-ab39-d449147d5cb4)

**Severe Delays:**

![Central Line - Severe Delays](https://github.com/user-attachments/assets/c680ae21-ea94-4050-9be5-81dc34d53431)

**Minor Delays:**

![Northern Line - Minor Delays](https://github.com/user-attachments/assets/e3f3b3dc-2b27-4445-b5b8-faa8708ce8ba)

The visual cards feature:
- Official TfL roundel logo with dynamic line colors
- Status badges (green for good service, red for severe delays, amber for minor delays)
- Clean, professional design with TfL branding
- Fully backward compatible - non-MCP-UI clients receive JSON data

### 🗺️ **plan_journey**
Plan journeys between two locations in London.
- **Parameters:**
  - `from`: Starting location (postcode, address, or station name)
  - `to`: Destination location (postcode, address, or station name)
  - `modes` (optional): Transport modes to use (e.g., 'tube,bus,walking')
  - `time` (optional): Journey time in HH:MM format or 'now'
  - `timeIs` (optional): 'Departing' or 'Arriving'
  - `date` (optional): Journey date in YYYYMMDD format
  - `walkingSpeed` (optional): 'Slow', 'Average', or 'Fast'
  - `cyclePreference` (optional): Cycling preference options
  - `optimize` (optional): 'Time', 'LeastInterchange', or 'LeastWalking'
  - `maxTransferMinutes` (optional): Maximum transfer time in minutes
  - `maxWalkingMinutes` (optional): Maximum walking time in minutes

## Getting Started

### Try It Now (No Deployment Required)

Want to test the server before deploying your own? You can use the public demo instance!

#### For Claude Desktop:
1. Open Claude Desktop Settings > Developer > Edit Config
2. Add this configuration:

```json
{
  "mcpServers": {
    "tfl": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://london-transport-mcp.anoopt.workers.dev/mcp"
      ]
    }
  }
}
```

3. Restart Claude Desktop
4. Start asking questions about London transport!

#### For VS Code (GitHub Copilot):
1. Open VS Code Settings > Extensions > GitHub Copilot > MCP Servers
2. Add this configuration:

```json
{
  "servers": {
    "tfl": {
      "type": "http",
      "url": "https://london-transport-mcp.anoopt.workers.dev/mcp"
    }
  }
}
```

3. Start the MCP server
4. Start using TfL tools in Copilot Chat!

### Quick Deploy

[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/anoopt/tfl-mcp-server)

Click the button above to deploy this MCP server to your Cloudflare Workers account with one click!

### Manual Deployment

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Deploy to Cloudflare Workers:
   ```bash
   npm run deploy
   ```

Your MCP server will be deployed to a URL like: `london-transport-mcp.<your-account>.workers.dev`

### Authentication (Optional)

This server supports optional TfL API key authentication. While the TfL API works without authentication, using an API key provides higher rate limits and better performance.

**Without API Key:**
The server will work with TfL's public API limits (subject to rate limiting).

**With API Key (Recommended):**
1. Get a free API key from [TfL API Portal](https://api-portal.tfl.gov.uk/)
2. Pass the API key in the `X-API-Key` header when connecting to the server

## Connect to Claude Desktop

To connect to your MCP server from Claude Desktop, update your Claude Desktop configuration:

1. Go to Claude Desktop Settings > Developer > Edit Config
2. Add one of the following configurations:

### Using mcp-remote

**With API Key:**
```json
{
  "mcpServers": {
    "tfl": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://london-transport-mcp.<your-account>.workers.dev/mcp",
        "--header",
        "X-API-Key: YOUR_TFL_API_KEY"
      ]
    }
  }
}
```

**Without API Key:**
```json
{
  "mcpServers": {
    "tfl": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://london-transport-mcp.<your-account>.workers.dev/mcp"
      ]
    }
  }
}
```

**Note:** For local development, replace the URL with `http://localhost:8787/mcp`

## Connect to Cloudflare AI Playground

You can also connect to your MCP server from the Cloudflare AI Playground:

1. Go to https://playground.ai.cloudflare.com/
2. Enter your deployed MCP server URL with the `/mcp` endpoint
3. Add the `X-API-Key` header with your TfL API key
4. Start using the TfL tools directly from the playground!

## Local Development

For local development:

```bash
npm run dev
```

This will start the server locally at `http://localhost:8787`

## API Key (Optional)

This server supports optional TfL API key authentication for higher rate limits. The API key is **not required** but recommended for production use.

**To use without an API Key:**
Simply omit the `X-API-Key` header when connecting. The TfL API will apply standard rate limits.

**To use with an API Key:**
1. Visit the [TfL API Portal](https://api-portal.tfl.gov.uk/)
2. Register for a free account
3. Create a new application to get your API key
4. Pass the key in the `X-API-Key` header when connecting

## Examples

Once connected, you can ask Claude things like:

- "Show me the line status selector" or "Show status" - displays an interactive UI with all TfL lines
- "Is the Northern line running ok?"
- "What's the status of the Victoria line?"
- "Plan a journey from King's Cross to Heathrow Airport"
- "How do I get from Oxford Circus to Canary Wharf?"
- "What's the fastest route from Wimbledon to Liverpool Street?"

## Tech Stack

- **Runtime**: Cloudflare Workers
- **Framework**: Hono.js
- **MCP SDK**: @modelcontextprotocol/sdk
- **Language**: TypeScript
- **API**: Transport for London Unified API

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is open source and available under the MIT License.