TMB Bus Arrival Times MCP Server

A Model Context Protocol (MCP) server that provides real-time bus arrival information for TMB (Transports Metropolitans de Barcelona) bus stops.

🚀 Features

• Real-time bus arrivals: Get up-to-date information about when buses will arrive

• Multiple lines support: See all bus lines serving a stop

• Time in minutes: Arrival times shown in minutes for easy understanding

• Detailed information: Line numbers, destinations, directions, and bus IDs

• MCP compliant: Works with any MCP client including Claude Desktop

📋 Prerequisites

• Node.js 18+

• npm or yarn

• TMB API credentials (get them at https://developer.tmb.cat/)

🔧 Installation

1. Clone or create the project:

2. Install dependencies:

3. Set up your TMB API credentials:

4. Build the project:

🎯 Usage

Option 1: Using the Client (Testing)

The client is perfect for testing and development:

Example output:

Option 2: Using with Claude Desktop

Add the server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Then restart Claude Desktop. You can now ask Claude things like:

• "What buses are coming to stop 2775?"

• "When is the next bus at Pl Espanya?"

• "Show me all bus arrivals for stop 108"

Option 3: Using the Host (Standalone)

Run the server independently:

🛠️ Architecture Explained

MCP Server (src/server.ts)

The core component that:

• Exposes the get_bus_arrivals tool via MCP protocol

• Handles communication with TMB's iBus API

• Transforms raw API responses into user-friendly formats

• Runs on stdio transport for easy integration

Key responsibilities:

• Tool registration and discovery

• Request validation

• API communication with error handling

• Data transformation and formatting

Host Application (src/host.ts)

A simple wrapper that:

• Starts the MCP server as a child process

• Manages environment variables

• Handles graceful shutdown

When to use: For standalone deployment or testing without an MCP client.

Client Application (src/client.ts)

A demonstration client that:

• Connects to the MCP server via stdio

• Lists available tools

• Calls tools with parameters

• Displays formatted results

When to use: For testing, development, or as a reference implementation.

🔌 API Integration Details

The server connects to TMB's iBus API:

Endpoint: https://api.tmb.cat/v1/itransit/bus/parades/{stopCode}

Parameters:

• app_id: Your TMB application ID

• app_key: Your TMB application key

Response structure:

📝 Type Safety

The project uses TypeScript with strict type checking. All API responses are properly typed in src/types.ts:

• TMBApiResponse: Raw API response structure

• BusStopInfo: Transformed, user-friendly format

• FormattedBusArrival: Individual line information

🧪 Testing Different Bus Stops

Try these Barcelona bus stops:

• 2775: Random stop

• 108: Pl Espanya - FGC

• 1: Pl Catalunya

• 2554: Sagrada Família

🔍 How It Works

1. Client Request: An MCP client (like Claude) calls the get_bus_arrivals tool with a stop code

2. Server Processing: The MCP server receives the request via stdio transport

3. API Query: Server makes an authenticated request to TMB's iBus API

4. Data Transformation: Raw API response is transformed into a readable format

5. Time Calculation: Arrival timestamps are converted to "minutes until arrival"

6. Response: Formatted text is returned to the client

🚦 Error Handling

The server handles various error scenarios:

• Missing credentials: Exits with clear error message

• Invalid stop code: Returns user-friendly error

• API errors: Catches and formats API error responses

• Network issues: Handles timeout and connection errors

🔐 Security Notes

• Never commit your .env file or API credentials

• The .env.example file shows the format without real credentials

• Credentials are passed via environment variables, not hardcoded

• Use MCP's built-in transport security for production deployments

📚 MCP Protocol Details

This server implements MCP (Model Context Protocol):

• Transport: stdio (standard input/output)

• Capabilities: Tools

• Tool Name: get_bus_arrivals

• Input: { stopCode: string }

• Output: Formatted text with bus arrival information

🤝 Contributing

To extend this server:

1. Add new tools in server.ts getTools() method

2. Implement handlers in handleToolCall()

3. Update types in types.ts as needed

4. Test with the client application

📄 License

MIT

🙏 Credits

• TMB API: https://developer.tmb.cat/

• MCP SDK: https://github.com/anthropics/modelcontextprotocol

Questions? Check the MCP documentation at https://modelcontextprotocol.io/