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 clients.

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

Tool	API endpoint	Description
find_station	/station/{pattern}	Search stations by name, EVA number, or DS100 code
get_departures	/plan/… + /fchg/… (merged)	Timetable for one hour slice (defaults to now), with real-time data: delays, platform changes, cancellations, added trips
get_live_changes	/fchg/{eva}	All known real-time changes for the current day
get_recent_changes	/rchg/{eva}	Only changes from the last 2 minutes (cheap polling)

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

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"]
    }
  }
}

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.