mcp-tfl-journey

TfL Journey MCP Server

A Model Context Protocol (MCP) server that provides journey information from Transport for London (TfL) API.

Project Structure

The project is organized into modular files following clean code principles:

mcp-tfl-journey/
├── index.js          # Main MCP server configuration and entry point
├── tfl-api.js        # TfL API communication and data fetching
├── helpers.js        # Utility functions for data extraction and processing
├── package.json      # Dependencies and project configuration
└── README.md         # This file

File Responsibilities

• index.js: MCP server setup, tool definitions, and request handlers
• tfl-api.js: API communication with TfL, data fetching, and response formatting
• helpers.js: Pure utility functions for extracting and processing journey data

Features

• Search for journey information between TfL stations
• Extract alerts, disruptions, and stop points from journey data
• Provide comprehensive journey summaries
• Clean, modular, and maintainable code structure

Installation & Usage

Option 1: Using npx (Recommended)

Run directly without installation:

npx mcp-tfl-journey

Option 2: Local Installation

1. Install dependencies:

   npm install

2. Set your TfL API key as an environment variable:

   export TFL_API_KEY="your-api-key-here"

3. Run the server:

   npm start
   # or
   node index.js

Configuration

Set your TfL API key as an environment variable:

export TFL_API_KEY="your-api-key-here"

You can get a free API key from TfL Developer Portal.

Usage

The server provides a search_journey tool that accepts:

• from: Source station code (e.g., "9400ZZLUKSX")
• to: Destination station code (e.g., "9400ZZLULVT")

Publishing to npm

To publish this package to npm:

1. Update the repository URL in package.json with your actual GitHub repository

2. Login to npm:

   npm login

3. Publish the package:

   npm publish

4. After publishing, users can run:

   npx mcp-tfl-journey

Code Quality

This project follows clean code principles:

• Single Responsibility: Each file has a clear, focused purpose
• Modularity: Functions are organized by their domain and responsibility
• Readability: Clear naming and documentation
• Maintainability: Easy to test, modify, and extend individual components

API Endpoint

The server uses the official TfL endpoint:

https://api.tfl.gov.uk/Journey/JourneyResults/{from}/to/{to}

Station Codes

Some examples of station codes:

• 9400ZZLUKSX: Kings Cross
• 9400ZZLULVT: Liverpool Street
• 9400ZZLUPAD: Paddington
• 9400ZZLUVIC: Victoria

For more station codes, please refer to the official TfL API documentation.