DB Timetable MCP Server

English | Deutsch

DB Timetable MCP Server

A Model Context Protocol server for the official Deutsche Bahn Timetables API. It converts the compact DB XML into semantic JSON and merges the planned schedule with live changes into one station board.

What it guarantees

• Correct platforms and times. effective holds the value to display. planned and changed explain the deviation.
• Output built for models. Tools return structuredContent, descriptive JSON schemas, and a data model available as an MCP resource.
• MCP conformance. Official TypeScript SDK, stdio for local clients, stateless Streamable HTTP for remote operation.
• Safe defaults. No logs on stdout, loopback binding unless you change it, host allowlist, timeouts, non-root container, reproducible lockfile.
• Verifiable behaviour. Unit, contract, and transport tests, coverage thresholds, CI, dependency and secret checks.

Quick start

Requirements: Node.js 22 or 24 LTS, and a subscribed Timetables product in the DB API Marketplace.

git clone https://github.com/jorekai/db-timetable-mcp.git
cd db-timetable-mcp
npm ci
cp .env.example .env

Fill in .env:

DB_TIMETABLE_CLIENT_ID=deine-client-id
DB_TIMETABLE_CLIENT_SECRET=dein-api-key

Then build and start:

npm run build
npm start

In stdio mode the process waits for an MCP client. Status messages go to stderr only. stdout stays reserved for JSON-RPC.

Claude Desktop

Run npm ci && npm run build first, then point the configuration at an absolute path in claude_desktop_config.json.

macOS/Linux:

{
  "mcpServers": {
    "db-timetable": {
      "command": "node",
      "args": ["/absolute/path/db-timetable-mcp/dist/index.js"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "db-timetable": {
      "command": "node",
      "args": ["C:\\absolute\\path\\db-timetable-mcp\\dist\\index.js"]
    }
  }
}

The .env file is looked up in the current working directory and next to the project directory, which covers the case where Claude Desktop starts the compiled server from somewhere else. You can also set the two credentials in the env object of the MCP entry instead.

After a configuration change, quit Claude Desktop completely and start it again. More in Troubleshooting.

Tools

Tool	Purpose
getStationBoard	Recommended. Joins the planned schedule and the full change set into a live station board
getPlannedTimetable	Static planned timetable for an EVA number, date, and hour
getCurrentTimetable	The complete change set (fchg), named this way for compatibility
getRecentChanges	Changes from the last two minutes (rchg) for incremental updates
findStations	Station search by name, EVA number, or DS100 code

Every tool takes an optional includeRawXml: true. The full reference with examples is in docs/api.md.

Data model

An arrival or departure event, abbreviated:

{
  "planned": { "time": { "local": "2026-07-17T10:20" }, "platform": "8" },
  "changed": { "time": { "local": "2026-07-17T10:27" }, "platform": "10" },
  "effective": { "time": { "local": "2026-07-17T10:27" }, "platform": "10" },
  "delayMinutes": 7,
  "platformChanged": true,
  "isCancelled": false
}

Use effective for anything a traveller sees. The model can retrieve the same explanation through the db-timetable://docs/data-model resource. Details in docs/data-model.md.

Streamable HTTP and Docker

Start it locally:

MCP_TRANSPORT=http npm start

• MCP endpoint: http://127.0.0.1:3000/mcp
• Health check: http://127.0.0.1:3000/health

With Docker Compose:

docker compose up --build -d
docker compose ps
curl http://127.0.0.1:3000/health

Compose binds the port to loopback on purpose, runs as an unprivileged user, and uses a read-only filesystem. A public endpoint additionally needs TLS and authentication behind a reverse proxy. ALLOWED_HOSTS must list every allowed hostname.

Configuration

Variable	Default	Description
DB_TIMETABLE_CLIENT_ID	–	DB client ID, required for API calls
DB_TIMETABLE_CLIENT_SECRET	–	DB API key, required for API calls
DB_TIMETABLE_BASE_URL	official v1 URL	Alternative base URL, mainly for tests
DB_TIMETABLE_TIMEOUT_MS	15000	Request timeout between 1000 and 120000 ms
MCP_TRANSPORT	stdio	stdio or http
HOST	127.0.0.1	HTTP bind address
PORT	3000	HTTP port
MCP_ENDPOINT	/mcp	Streamable HTTP path
ALLOWED_HOSTS	–	Comma-separated host allowlist, required with 0.0.0.0/::
DOTENV_CONFIG_PATH	–	Explicit absolute path to an env file
LOG_LEVEL	info	debug, info, warn, or error

The old values TRANSPORT_TYPE=sse|httpStream and SSE_ENDPOINT still map to Streamable HTTP, so migration does not break an existing client.

Development

npm run dev          # stdio with watch mode
npm run dev:http     # Streamable HTTP with watch mode
npm run check        # lint, types, tests, and build
npm run test:coverage

Further reading:

• API reference
• Data model
• Architecture
• Testing strategy
• Contributing
• Security policy
• Changelog

The documents under docs/ are currently written in German.

Troubleshooting

Expected "," or "]" after array element in Claude Desktop

Update to version 2 and rebuild. Earlier versions wrote log lines to the stdio protocol channel. Version 2 uses stderr for that.

DB-API-Zugangsdaten fehlen even though .env exists (the message reads "DB API credentials are missing")

The file must sit in the repository root next to package.json. If it lives somewhere else, set DOTENV_CONFIG_PATH to an absolute path. Do not wrap the values in quotes or leave trailing spaces around them.

401/403 from the DB API

Check that the client ID and the API key belong together, and that the application has subscribed to the Timetables product.

Wrong platform

Use getStationBoard and read effective.platform. planned.platform is the scheduled platform by definition, and changed.platform is present only when DB has reported a change.

Data source and license

The timetable data comes from Deutsche Bahn and is served through the Timetables API 1.0.274. According to the DB API Marketplace the data is under CC BY 4.0, so attribution to Deutsche Bahn is required when you use it. The Marketplace currently states a limit of 60 calls per minute.

The MCP server itself is under the MIT license.