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

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

Related MCP server: MCP Trenitalia

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

Or test interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector uv 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 50k characters. 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.

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.