DB Timetable MCP Server

English | Deutsch

DB Timetable MCP 服务

一个用于 Deutsche Bahn 官方 Timetables API 的模型上下文协议服务。它会将精简的 DB XML 转换为语义化 JSON，并将计划时刻表与实时变更合并为一份车站时刻表。

保证内容

• 站台和时间准确。 effective 保存要显示的值。planned 和 changed 用于说明偏差。
• 专为模型打造的输出。 工具会返回 structuredContent、描述性 JSON 架构，以及可作为 MCP 资源使用的数据模型。
• 符合 MCP 规范。 使用官方 TypeScript SDK，本地客户端使用 stdio，远程运行使用无状态的 Streamable HTTP。
• 安全的默认设置。 不向 stdout 写入日志；除非另行更改，否则绑定到回环地址；支持主机允许列表、超时、非 root 容器和可复现的锁文件。
• 行为可验证。 包含单元测试、契约测试和传输测试，并设置覆盖率阈值，执行 CI、依赖项和密钥检查。

快速开始

要求：Node.js 22 或 24 LTS，以及在 DB API Marketplace 订阅的 Timetables 产品。

git clone https://github.com/jorekai/db-timetable-mcp.git
cd db-timetable-mcp
npm ci
cp .env.example .env

填写 .env：

DB_TIMETABLE_CLIENT_ID=deine-client-id
DB_TIMETABLE_CLIENT_SECRET=dein-api-key

然后构建并启动：

npm run build
npm start

在 stdio 模式下，进程会等待 MCP 客户端连接。状态消息仅写入 stderr。stdout 专用于 JSON-RPC。

Claude Desktop

先运行 npm ci && npm run build，然后在 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"]
    }
  }
}

系统会在当前工作目录和项目目录旁查找 .env 文件，因此即使 Claude Desktop 从其他位置启动已编译的服务，也能正常工作。你也可以在 MCP 条目的 env 对象中设置这两个凭据。

更改配置后，请完全退出 Claude Desktop 并重新启动。更多信息请参阅故障排除。

工具

工具	用途
getStationBoard	推荐使用。将计划时刻表与完整变更集合并为实时车站时刻表
getPlannedTimetable	指定 EVA 编号、日期和小时的静态计划时刻表
getCurrentTimetable	完整变更集（fchg），为兼容性而采用此名称
getRecentChanges	最近两分钟的变更（rchg），用于增量更新
findStations	按名称、EVA 编号或 DS100 代码搜索车站

每个工具都支持可选参数 includeRawXml: true。完整参考资料和示例见 docs/api.md。

数据模型

到达或出发事件的简略示例：

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

对于旅客会看到的所有内容，请使用 effective。模型可以通过 db-timetable://docs/data-model 资源获取相同的说明。详情见 docs/data-model.md。

Streamable HTTP 和 Docker

在本地启动：

MCP_TRANSPORT=http npm start

• MCP 端点：http://127.0.0.1:3000/mcp
• 健康检查：http://127.0.0.1:3000/health

使用 Docker Compose：

docker compose up --build -d
docker compose ps
curl http://127.0.0.1:3000/health

Compose 会有意将端口绑定到回环地址，以非特权用户身份运行，并使用只读文件系统。若要公开端点，还需在反向代理后配置 TLS 和身份验证。ALLOWED_HOSTS 必须列出所有允许的主机名。

配置

变量	默认值	说明
DB_TIMETABLE_CLIENT_ID	–	DB 客户端 ID，API 调用必需
DB_TIMETABLE_CLIENT_SECRET	–	DB API 密钥，API 调用必需
DB_TIMETABLE_BASE_URL	official v1 URL	替代基础 URL，主要用于测试
DB_TIMETABLE_TIMEOUT_MS	15000	请求超时时间，介于 1000 到 120000 毫秒之间
MCP_TRANSPORT	stdio	stdio 或 http
HOST	127.0.0.1	HTTP 绑定地址
PORT	3000	HTTP 端口
MCP_ENDPOINT	/mcp	Streamable HTTP 路径
ALLOWED_HOSTS	–	以逗号分隔的主机允许列表；使用 0.0.0.0/:: 时必需
DOTENV_CONFIG_PATH	–	环境文件的显式绝对路径
LOG_LEVEL	info	debug、info、warn 或 error

旧值 TRANSPORT_TYPE=sse|httpStream 和 SSE_ENDPOINT 仍会映射到 Streamable HTTP，因此迁移不会导致现有客户端无法使用。

开发

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

延伸阅读：

• API 参考
• 数据模型
• 架构
• 测试策略
• 贡献指南
• 安全政策
• 变更日志

docs/ 下的文档目前以德语编写。

故障排除

Claude Desktop 中出现 Expected "," or "]" after array element

请升级到版本 2 并重新构建。早期版本会将日志行写入 stdio 协议通道。版本 2 会将其写入 stderr。

尽管存在 .env，仍出现 DB-API-Zugangsdaten fehlen（消息意为“缺少 DB API 凭据”）

该文件必须放在仓库根目录，与 package.json 同级。如果文件位于其他位置，请将 DOTENV_CONFIG_PATH 设置为绝对路径。请勿给值加引号，也不要在值的前后留空格。

DB API 返回 401/403

请检查客户端 ID 和 API 密钥是否匹配，以及应用是否已订阅 Timetables 产品。

站台错误

使用 getStationBoard 并读取 effective.platform。根据定义，planned.platform 是计划站台；只有 DB 报告了变更时，才会提供 changed.platform。

数据来源和许可证

时刻表数据来自 Deutsche Bahn，并通过 Timetables API 1.0.274 提供。根据 DB API Marketplace 的说明，数据采用 CC BY 4.0 许可，因此使用时必须注明 Deutsche Bahn。Marketplace 目前规定每分钟最多调用 60 次。

MCP 服务本身采用 MIT 许可证。