smithery badge

DB Timetable MCP Server

A standardized Model Context Protocol (MCP) server that provides seamless access to Deutsche Bahn's timetable data through MCP tools and resources. This server enables AI assistants and applications to query real-time train schedules, station information, and timetable changes for German railway stations.

Overview

This MCP server bridges the gap between AI applications and Deutsche Bahn's timetable API, offering:

• Real-time timetable access - Get current train schedules and platform information
• Change tracking - Monitor real-time updates, delays, and platform changes
• Station search - Find stations by name or EVA number
• Planned schedules - Access future timetable data for trip planning

Built with the standard @modelcontextprotocol/sdk, this server supports both stdio and SSE (Server-Sent Events) transport modes, making it compatible with various MCP clients including Cursor IDE.

Data Source & License

This project provides timetable data from Deutsche Bahn, which is publicly available under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

For more information about the API and license terms, visit developers.deutschebahn.com. All API requests are subject to the license terms.

Key Features

• Real-time Timetables - Get current train schedules with platform assignments, delays, and real-time updates
• Change Tracking - Monitor live timetable changes including delays, cancellations, and platform modifications
• Planned Schedules - Access future timetable data for specific dates and times
• Station Discovery - Search and find German railway stations by name, code, or pattern matching
• Dual Transport Modes - Support for both stdio (CLI) and SSE (HTTP) transport protocols
• Cursor IDE Integration - Ready-to-use configuration for seamless Cursor IDE integration

Prerequisites

• Node.js 18 or higher
• API credentials for the DB Timetable API (Client ID and Client Secret)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd db-timetable-mcp
   

2. Install dependencies:

   npm install
   

3. Compile TypeScript code:

   npm run build
   

Configuration

Create a .env file in the project root directory with the following environment variables:

DB_TIMETABLE_CLIENT_ID=your-client-id
DB_TIMETABLE_CLIENT_SECRET=your-client-secret
TRANSPORT_TYPE=sse
PORT=3000
SSE_ENDPOINT=/sse
LOG_LEVEL=info

Configuration Options

• DB_TIMETABLE_CLIENT_ID: Client ID for the DB API (required)
• DB_TIMETABLE_CLIENT_SECRET: Client Secret for the DB API (required)
• TRANSPORT_TYPE: Transport type for the MCP server (stdio or sse, default: stdio)
• PORT: Port for the SSE server (default: 3000)
• SSE_ENDPOINT: Endpoint for SSE connections (default: /sse)
• LOG_LEVEL: Logging level (debug, info, warn, error, default: info)

Usage

Starting the Server

In stdio mode (for CLI tests and debugging):

npm start

In SSE mode (for web clients):

TRANSPORT_TYPE=sse npm start

Or use the dev script:

npm run dev:sse

MCP Tools

The server provides the following tools:

1. getCurrentTimetable: Retrieves current timetable data for a station

   • Parameters: evaNo - EVA number of the station (e.g., 8000105 for Frankfurt Hbf)

2. getRecentChanges: Retrieves recent changes for a station

   • Parameters: evaNo - EVA number of the station (e.g., 8000105 for Frankfurt Hbf)

3. getPlannedTimetable: Retrieves planned timetable data for a station

   • Parameters:
     • evaNo - EVA number of the station (e.g., 8000105 for Frankfurt Hbf)
     • date - Date in YYMMDD format (e.g., 230401 for April 1, 2023)
     • hour - Hour in HH format (e.g., 14 for 2 PM)

4. findStations: Searches for stations by pattern

   • Parameters: pattern - Search pattern (e.g., "Frankfurt" or "BLS")

MCP Resources

The server provides the following resources:

1. Current Timetable: db-api:timetable/current/{evaNo}
2. Recent Changes: db-api:timetable/changes/{evaNo}
3. Planned Timetable: db-api:timetable/planned/{evaNo}/{date}/{hour}
4. Station Search: db-api:station/{pattern}

Development

Project Structure

db-timetable-mcp/
├── src/
│   ├── api/             # API client and types
│   ├── tools/           # MCP tools
│   ├── resources/       # MCP resources
│   ├── utils/           # Utility functions
│   ├── config.ts        # Configuration
│   └── index.ts         # Main entry point
├── dist/                # Compiled files
├── .env                 # Environment variables
├── package.json
├── tsconfig.json
└── README.md

NPM Scripts

• npm run build: Compiles TypeScript code
• npm start: Starts the server
• npm run dev: Starts the server in development mode
• npm run dev:sse: Starts the server in SSE mode (development)
• npm test: Runs tests
• npm run check-env: Checks environment variable configuration

Cursor Integration

This server can be integrated with Cursor IDE. See CURSOR_CONFIG.md for detailed configuration instructions.

Quick Setup

1. Start the server in SSE mode:

   npm run dev:sse
   

2. Add to Cursor's MCP configuration:

   {
     "mcpServers": {
       "db-timetable": {
         "url": "http://localhost:3000/sse",
         "transport": "sse"
       }
     }
   }
   

REST API Endpoints

The server also provides REST API endpoints for testing:

• GET /health - Health check
• GET /tools - List all tools
• GET /resources - List all resources
• POST /tools/call - Call a tool (REST API)
• GET /sse - SSE connection endpoint
• POST /sse - Send MCP messages via SSE (JSON-RPC 2.0)

Extensibility

Potential extensions:

1. Data Processing and Enrichment

   • Semantic timetable data processing: XML to structured JSON with semantic enrichment
   • Historical data analysis for delays and operational disruptions
   • Integration of multimodal transport connections

2. Advanced MCP Tools

   • Route planning between stations
   • AI-based delay and capacity forecasts
   • Travel disruption analysis
   • Accessibility check for stations and connections

License

MCP Server: MIT License

DB Timetable API: Creative Commons Attribution 4.0 International License