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:

mkdir tmb-bus-mcp
cd tmb-bus-mcp

2. Install dependencies:

npm install

3. Set up your TMB API credentials:

# Copy the example environment file
cp .env.example .env

# Edit .env and add your credentials
# TMB_APP_ID=your_app_id
# TMB_APP_KEY=your_app_key

4. Build the project:

npm run build

🎯 Usage

Option 1: Using the Client (Testing)

The client is perfect for testing and development:

# Set environment variables
export TMB_APP_ID=your_app_id
export TMB_APP_KEY=your_app_key

# Query a specific bus stop
npm run client 2775

# List available tools
npm run client -- list

Example output:

🚌 Bus Stop: Pl Espanya - FGC (108)
📅 Query Time: 11/6/2025, 10:30:00 AM

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚍 Line H12 (212) → Gornal
   Direction: return

   Next arrivals:
   • ⏱️  2 min (at 10:32:00) - Bus #3673
   • ⏱️  16 min (at 10:46:00) - Bus #8531

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

{
  "mcpServers": {
    "tmb-bus": {
      "command": "node",
      "args": ["/absolute/path/to/tmb-bus-mcp/dist/server.js"],
      "env": {
        "TMB_APP_ID": "your_app_id",
        "TMB_APP_KEY": "your_app_key"
      }
    }
  }
}

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:

export TMB_APP_ID=your_app_id
export TMB_APP_KEY=your_app_key
npm run host

🛠️ 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:

{
  timestamp: number,              // Query timestamp
  parades: [{
    codi_parada: string,         // Stop code
    nom_parada: string,          // Stop name
    linies_trajectes: [{         // Lines serving this stop
      codi_linia: string,        // Line code
      nom_linia: string,         // Line name
      desti_trajecte: string,    // Destination
      id_sentit: number,         // 1=Outbound, 2=Return
      propers_busos: [{          // Upcoming buses
        temps_arribada: number,  // Arrival timestamp
        id_bus: number          // Bus identifier
      }]
    }]
  }]
}

📝 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

┌─────────┐         ┌──────────┐         ┌─────────┐
│  Client │────────▶│   MCP    │────────▶│   TMB   │
│ (Claude)│         │  Server  │         │   API   │
└─────────┘         └──────────┘         └─────────┘
     ▲                    │                    │
     │                    ▼                    │
     │              Transform Data             │
     │                    │                    │
     └────────────────────┴────────────────────┘

🚦 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/