# 🚇 TfL MCP Server

A Model Context Protocol (MCP) server that gives Claude AI real-time access to Transport for London (TfL) data. Ask Claude about tube status, plan journeys, check arrivals, and more — all through natural language.

## 🎥 Demo

Ask Claude things like:
- *"Is the Elizabeth line running?"*
- *"How do I get from Seven Kings to Canary Wharf?"*
- *"Any disruptions on TfL today?"*
- *"When is the next bus at stop 55354?"*
- *"How much is a journey from Seven Kings to Liverpool Street?"*

## 🛠 Tools Available

| Tool | Description |
|------|-------------|
| `get_line_status` | Status of a specific TfL line |
| `get_all_lines_status` | Status of ALL TfL lines at once |
| `get_station_info` | Station details (zone, modes, ID) |
| `get_arrivals` | Next train arrivals at a station |
| `plan_journey` | Full journey plan between two locations |
| `get_journey_time` | Fastest journey time between two locations |
| `get_bus_arrivals` | Next buses at a bus stop |
| `get_bus_route` | Full route of a bus |
| `get_fare` | Journey fare estimate |
| `search_station` | Search for a station by name |
| `get_nearby_stations` | Stations near a postcode |
| `get_disruptions` | Current network disruptions |
| `get_planned_works` | Upcoming engineering works |

## 🚀 Getting Started

### Prerequisites
- Node.js 18+
- Claude Desktop

### Installation

1. **Clone the repository:**
```bash
git clone https://github.com/Rumaisa10/tfl-mcp.git
cd tfl-mcp
```

2. **Install dependencies:**
```bash
npm install
```

3. **Build:**
```bash
npm run build
```

4. **Add to Claude Desktop config:**

Find your config file:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the following:
```json
{
  "mcpServers": {
    "tfl-mcp": {
      "command": "node",
      "args": ["/full/path/to/tfl-mcp/build/index.js"]
    }
  }
}
```

5. **Restart Claude Desktop**

6. **Ask Claude anything about TfL!** 🚇

## 📁 Project Structure

tfl-mcp/
├── src/
│ ├── index.ts ← MCP server entry point
│ ├── tools.ts ← Tool definitions
│ ├── handlers.ts ← Tool logic
│ └── tfl/
│ ├── client.ts ← TfL API base fetch helper
│ ├── lines.ts ← Line status functions
│ ├── stations.ts ← Station functions
│ ├── journey.ts ← Journey planning
│ ├── bus.ts ← Bus functions
│ ├── fares.ts ← Fare functions
│ └── disruptions.ts← Disruption functions
├── build/ ← Compiled JavaScript
├── package.json
└── tsconfig.json

## 🔑 API Key

This server uses the TfL Unified API which works without an API key for up to 50 requests/minute. For higher rate limits, register at [api.tfl.gov.uk](https://api.tfl.gov.uk) and add your credentials as query parameters in `src/tfl/client.ts`.

## 🌐 Supported Lines
elizabeth → Elizabeth line
central → Central line
jubilee → Jubilee line
northern → Northern line
victoria → Victoria line
dlr → DLR
overground → London Overground
bakerloo → Bakerloo line
piccadilly → Piccadilly line
district → District line
circle → Circle line
hammersmith → Hammersmith & City line
metropolitan → Metropolitan line

## 🤝 Contributing

Pull requests welcome! Feel free to add more TfL tools or improve existing ones.

## 📄 License

MIT

## 👩‍💻 Built by

[Romysa Sultana](https://github.com/Rumaisa10) — Frontend Developer based in London