db-fahrplan-mcp

An (unofficial) MCP server for the Deutsche Bahn Timetables API - station search, planned departures and real-time changes (delays, platform changes, cancellations) as tools for Claude and other MCP hosts.

Written in Python with FastMCP. The API's XML responses are parsed into compact JSON server-side, so tool outputs stay small and readable for the model.

Tools

Typical flow: find_station("Aachen Hbf") → EVA number → get_departures(eva_no).

Definitions

• EVA number — the unique numeric ID for a station in DB's systems (e.g. 8000001 = Aachen Hbf). Station names change and duplicate; EVA numbers don't, so every endpoint below keys off of it.

• plan — the static, pre-planned timetable for one hour at a station. Never contains delays, only what should happen.

• fchg ("full changes") — every known real-time change (delay, platform swap, cancellation, added trip) for the current operating day. Updated every 30s.

• rchg ("recent changes") — a small subset of fchg: only changes from the last 2 minutes. Cheaper to poll frequently once you've already loaded fchg once.

• DS100 — DB's short alphabetic code for a station (e.g. KA for Aachen Hbf), used internally alongside the EVA number.

Related MCP server: MCP Trenitalia

Example

Prompt:

When's the next train from Aachen Hbf?

The agent calls find_station("Aachen Hbf"), then get_departures(eva_no="8000001"), and answers from the result:

{
  "id": "-5414170453134686351-2607131018-1",
  "train": "RE 92111",
  "line": "RE9",
  "departure": {
    "planned_time": "2026-07-13T10:18",
    "changed_time": "2026-07-13T10:20",
    "delay_minutes": 2,
    "platform": "3",
    "destination": "Düren"
  }
}

RE9 to Düren, platform 3, 10:18 → running 2 min late, now 10:20.

Example: historical delay pattern

Prompt:

How punctual has RE9 been today at Stolberg(Rheinl)Hbf?

The agent calls find_station("Stolberg(Rheinl)Hbf"), then get_live_changes(eva_no="8000348", limit=100), filters the stops to line == "RE9", and reasons over the delay_minutes across the day:

[
  { "train": "RE 92111", "delay_minutes": 2 },
  { "train": "RE 92106", "delay_minutes": 1 },
  { "train": "RE 92118", "delay_minutes": 1 },
  { "train": "RE 92123", "delay_minutes": 0 },
  { "train": "RE 92125", "delay_minutes": 0 }
]

RE9 has been very reliable today: 0–2 min delay across 5 trips, no cancellations. get_live_changes covers the whole operating day in one call, so this needs no extra polling — just one fetch per station.

Setup

Requirements: Python ≥ 3.10, uv, free DB API credentials.

1. Get credentials — register at the DB API Marketplace, create an application, and subscribe it to the Timetables API. This gives you a Client ID and an API key.

2. Clone and configure:

git clone https://github.com/eric134422/db-fahrplan-mcp.git
cd db-fahrplan-mcp
uv sync
cp .env.example .env   # then paste your credentials into .env

3. Register with your MCP client — e.g. Claude Code (.mcp.json):

{
  "mcpServers": {
    "db-fahrplan": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/db-fahrplan-mcp", "run", "server.py"]
    }
  }
}

MCP servers are only picked up on startup, so restart your CLI tool (e.g. claude) after editing the config — a running session won't see the new server until it's relaunched.

Architecture

server.py   MCP layer: FastMCP instance + the four @mcp.tool()s (stdio transport)
api.py      HTTP layer: httpx client, auth headers, error mapping
parser.py   Translation layer: DB's XML → compact JSON dicts

The layers are deliberately independent: api.py knows nothing about MCP, parser.py knows nothing about HTTP. Swap or test each in isolation.

Why a parsing layer?

The Timetables API returns XML with single-letter attributes (pt = planned time, ct = changed time, pp/cp = planned/changed platform, ppth = route). Passing that to an LLM raw wastes context and invites misreading — a single /fchg response can exceed 800k characters for a major hub. parser.py maps the attributes to named JSON fields, computes delay_minutes, resolves origin/destination from the route path, and drops empty fields. get_live_changes additionally caps the stop list (limit parameter, default 30) and reports the total count.

The attribute semantics come from the official OpenAPI spec — download Timetables-*.json from the DB API Marketplace for the full dictionary.

API quirks worth knowing

• EVA numbers are the primary key for everything (8000001 = Aachen Hbf). German stations start with 80.

• Station search is a prefix match on exact DB naming: Stolberg(Rheinl)Hbf works, Stolberg Hbf doesn't. Umlauts often fail; * works as a wildcard.

• Times in the raw API are YYMMddHHmm strings in German local time; the parser converts them to ISO (2026-07-13T14:47).

• /plan slices are static — they never contain delays. Real-time data lives exclusively in /fchg and /rchg, which is why get_departures fetches both and merges them server-side.

• Fernverkehr (ICE/IC/EC/NJ) is included, not just regional RE/RB/S — but in /fchg, an on-time long-distance train can show up as a bare stop (timestamps only, no line/train field), since the name is only attached to records that carry an actual delay/disruption. Use /plan (get_departures) if you need reliable train names for Fernverkehr.

Roadmap

• Tests (pytest, mocked API responses)

• get_train — follow a single trip across stations

• Optional full route (via stations) in departure output

• MCPB packaging

Contributions welcome — the codebase is intentionally small and readable. Fragen und Issues gerne auch auf Deutsch.

License

MIT. Not affiliated with Deutsche Bahn AG. API data is subject to the DB API terms.