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

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

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.