Skip to main content
Glama
Sign In
db-timetables-mcp

db-timetables-mcp

by kukshaus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

db-timetables-mcp

MCP server for live Deutsche Bahn station boards. Ask Claude (or any MCP client) things like:

  • "When does the next train leave Dresden Hbf?"

  • "Is the ICE to Berlin from Leipzig delayed?"

  • "Any platform changes or cancellations at Köln Hbf in the next 2 hours?"

It uses the official DB Timetables API and merges the planned timetable with the live changes feed. It is read-only.

Tools

Tool

What it returns

find_station

Station name → EVA number and DS100 code

departures

Departure board: planned and expected time, delay, platform (and if it changed), cancellations, disruption messages, route

arrivals

Same data for arrivals, with the origin of each train

departures and arrivals accept a station name or an EVA number, an optional start time (local Berlin time in ISO format, default now), hours (1–6) and limit.

Related MCP server: irail-mcp

Setup

  1. Create a free account at developers.deutschebahn.com, create an application and subscribe it to the Timetables API (the free plan allows 60 calls/min).

  2. Copy your Client ID and Client Secret (API Key).

  3. Add the server to your MCP client.

Claude Code

git clone https://github.com/kukshaus/db-timetables-mcp.git
claude mcp add db-timetables -s user \
  -e DB_CLIENT_ID=your-client-id -e DB_API_KEY=your-api-key \
  -- uv --directory /path/to/db-timetables-mcp run db-timetables-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "db-timetables": {
      "command": "uv",
      "args": ["--directory", "/path/to/db-timetables-mcp", "run", "db-timetables-mcp"],
      "env": { "DB_CLIENT_ID": "your-client-id", "DB_API_KEY": "your-api-key" }
    }
  }
}

On macOS you can keep the keys out of config files and store them in the Keychain instead. The server reads them when the env vars are missing:

security add-generic-password -s db-api-client-id -a "$USER" -w 'your-client-id'
security add-generic-password -s db-api-key -a "$USER" -w 'your-api-key'

Example output

22:12  RE 50     → Leipzig Hbf        platform 9
22:18  S 2       → Dresden Flughafen  platform 14
22:22  TLX 76537 → Görlitz            platform 14

Development

uv sync
uv run pytest

Limits

  • Covers stations operated by DB Station&Service (all major German stations).

  • No journey planning (A → B with transfers). The Timetables API is per station.

  • The free plan allows 60 requests/min. One board for 1 hour costs 2 requests.

License

MIT. Not affiliated with Deutsche Bahn AG. Data © DB Station&Service AG via the DB API Marketplace.

Available Tools

3 tools
arrivalsArrivalsB
Read-only

Arrival board with live delays, platform changes, cancellations and messages.

NameRequiredDescriptionDefault
hoursNoHow many hours to look ahead
limitNo
startNoLocal Berlin time, ISO format. Default: now
stationYesStation name (e.g. 'Berlin Hbf') or EVA number

Output Schema

NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a live, side-effect-free read. The description adds a useful inventory of what the board surfaces (delays, platform changes, cancellations, messages), but says nothing about freshness, coverage window behavior, or failure modes for unknown stations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence, front-loaded with the resource and enriched with the concrete data categories. No filler, no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. However, for a tool that requires a station identifier and competes directly with 'departures' and 'find_station', the absence of routing guidance leaves a real gap for an agent choosing between them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, with 'hours' and 'start' already documented (including the Berlin-local ISO requirement), so the schema carries most of the load. The description adds no parameter meaning at all — notably nothing about the default one-hour look-ahead or the 100-row limit, which a caller might reasonably want framed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific resource (arrival board) plus the data it carries: live delays, platform changes, cancellations and messages. It is clearly distinct from 'departures' by subject matter, though it never names that sibling, so differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance: nothing says to pick this over 'departures' for inbound trains, and nothing hints that 'find_station' should be used first to resolve a station name into an EVA number. The intended usage is only inferable from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

departuresDeparturesA
Read-only

Departure board with live delays, platform changes, cancellations and messages.

NameRequiredDescriptionDefault
hoursNoHow many hours to look ahead
limitNo
startNoLocal Berlin time, ISO format. Default: now
stationYesStation name (e.g. 'Berlin Hbf') or EVA number

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, so safety and network behavior are covered. The description adds meaningful content context beyond that: the board is live and includes delays, platform changes, cancellations and free-text messages, which tells the agent what to expect in the response. It does not mention failure behavior for unknown stations, which is the remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with no filler, front-loading the resource and then listing the contents. Nothing is redundant with the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. What is missing is any routing hint to 'find_station' for an unresolvable station name and any note about the one undocumented parameter, so it falls just short of fully complete for a 4-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75% and the schema documents 'hours', 'start' (Berlin local time, ISO) and 'station' formats. The description adds no parameter-level meaning at all, notably nothing about the undocumented 'limit' or the interaction between 'hours' and 'start'. Baseline 3 is appropriate given the schema does most of the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (departure board) and enumerates the payload contents (live delays, platform changes, cancellations, messages), so an agent can tell what data it returns. It does not explicitly contrast itself with the sibling 'arrivals' or 'find_station', relying on the tool name alone for that distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus 'arrivals' (same station, opposite direction) or 'find_station' (for resolving a station name or EVA number). Usage is only implied by the name and the required 'station' parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_stationFind StationB
Read-only

Find German railway stations by name. Returns name, EVA number and DS100 code.

NameRequiredDescriptionDefault
queryYesStation name or part of it, e.g. 'Dresden Hbf' or 'Köln'

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the operation as read-only and open-world. The description adds useful return content (name, EVA number, DS100 code) but does not mention matching behavior, empty results, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no wasted wording. The core action and return fields are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter lookup with an output schema, this is nearly complete. The main minor gap is that it does not explain how partial-name matching works or what happens when no station is found.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the single query parameter is fully documented in the schema with examples. The description adds no syntax or matching details beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: find German railway stations by name. It is clearly distinguishable from the sibling departure and arrival tools, though it does not explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance or relationship to the sibling tools. An agent must infer that this is a station lookup step before querying departures or arrivals.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedarrivals
    • First observeddepartures
    • First observedfind_station
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: one resolves station names to identifiers, one returns outbound departures, one returns inbound arrivals. There is no plausible way an agent would misselect among them.

Naming Consistency3/5

find_station follows a verb_noun pattern while departures and arrivals are bare plural nouns, so the convention is mixed. The names are still unambiguous and readable, but there is no single predictable pattern an agent can rely on.

Tool Count4/5

Three tools is on the thin side, but for a narrow live-board service each tool earns its place, and the station lookup is a necessary prerequisite for the two board tools. It is slightly minimal rather than bloated.

Completeness3/5

Station lookup plus live departure and arrival boards cover the core lookup flow, but the surface has notable gaps for a 'timetables' domain: no journey/connection planning, no scheduled timetable for a specific train, and no way to query a board by station ID without re-searching. Agents needing trip planning will hit a dead end.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers