[![smithery badge](https://smithery.ai/badge/@jorekai/db-timetable-mcp)](https://smithery.ai/server/@jorekai/db-timetable-mcp)

# 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)](https://creativecommons.org/licenses/by/4.0/).

For more information about the API and license terms, visit [developers.deutschebahn.com](https://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:
   ```bash
   git clone <repository-url>
   cd db-timetable-mcp
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Compile TypeScript code:
   ```bash
   npm run build
   ```

## Configuration

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

```env
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):

```bash
npm start
```

In SSE mode (for web clients):

```bash
TRANSPORT_TYPE=sse npm start
```

Or use the dev script:

```bash
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](./CURSOR_CONFIG.md) for detailed configuration instructions.

### Quick Setup

1. Start the server in SSE mode:
   ```bash
   npm run dev:sse
   ```

2. Add to Cursor's MCP configuration:
   ```json
   {
     "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](https://developers.deutschebahn.com/db-api-marketplace/apis/product/timetables)