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
- Clone or create the project:
mkdir tmb-bus-mcp
cd tmb-bus-mcp
- Install dependencies:
npm install
- 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
- 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_arrivalstool 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 IDapp_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 structureBusStopInfo: Transformed, user-friendly formatFormattedBusArrival: Individual line information
🧪 Testing Different Bus Stops
Try these Barcelona bus stops:
2775: Random stop108: Pl Espanya - FGC1: Pl Catalunya2554: Sagrada Família
🔍 How It Works
- Client Request: An MCP client (like Claude) calls the
get_bus_arrivalstool with a stop code - Server Processing: The MCP server receives the request via stdio transport
- API Query: Server makes an authenticated request to TMB's iBus API
- Data Transformation: Raw API response is transformed into a readable format
- Time Calculation: Arrival timestamps are converted to "minutes until arrival"
- 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
.envfile or API credentials - The
.env.examplefile 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:
- Add new tools in
server.tsgetTools()method - Implement handlers in
handleToolCall() - Update types in
types.tsas needed - 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/