Deutsche Bahn MCP Server

Deutsche Bahn MCP 服务

一个全面的 Model Context Protocol（MCP）服务，可统一访问 Deutsche Bahn（DB）和德国出行 API。该服务使用 Python、FastAPI 和 FastMCP 构建，可与 Claude Desktop 和其他 MCP 客户端无缝集成。

该服务已准备好进行本地和云端部署。可通过将 URL 添加到 MCP 客户端来连接正在运行的 MCP 服务：[SERVER DECOMISSIONED - HOST YOUR OWN DEPLOYMENT AS DESCRIBED]。

🚀 功能

• 🚄 完整的铁路数据：车站、时刻表、实时运营中断信息和停车场
• 🤖 MCP 协议：全面支持工具、提示词和资源
• 🛡️ 可用于生产环境：安全标头、速率限制、输入验证
• 🏗️ 模块化架构：简洁、易维护的代码库结构
• ☁️ 云原生：专为部署到 Google Cloud Run 而设计
• 📚 丰富的文档：全面的指南和参考资料

📋 快速开始（面向开发者——用户说明见下文）

先决条件

• Python 3.11+
• Deutsche Bahn API 凭据（在此获取）
• Google Cloud 账号（用于部署）

本地开发

1. 克隆并设置：

   git clone <repository-url>
   cd deutsche-bahn-mcp-server
   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   

2. 配置环境：

   cp .env.example .env
   

   接下来，编辑新建的 .env 文件，填入 DB API 凭据。有关各个变量的详情，请参阅“配置”部分。

3. 运行服务：

   python main.py
   # Server available at http://localhost:8080
   

🎯 在线服务使用指南

[SERVER DECOMISSIONED - HOST YOUR OWN DEPLOYMENT AS DESCRIBED]

🖥️ Claude Desktop 设置

步骤 1：找到配置文件

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\\Claude\\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

步骤 2：编辑配置 打开文件并添加 Deutsche Bahn 服务：

{
  "mcpServers": {
    "deutschebahn": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://[SERVER DECOMISSIONED - Use your URL]/mcp",
        "--transport", "http-only"
      ]
    }
  }
}

步骤 3：重启 Claude Desktop

• 完全关闭 Claude Desktop
• 重新打开应用程序
• 你应该会在 MCP 部分看到“Deutsche Bahn MCP Server”

步骤 4：测试连接 向 Claude 提问：“柏林有哪些火车站？”

🌐 在 Claude.ai 网页版中使用

步骤 1：开始对话 前往 claude.ai 并开始新对话。

步骤 2：添加 MCP 服务 点击 “Search and Tools > Add connectors > Manage connectors” 选择 “Add custom connector” 输入名称，例如：“Deutsche Bahn MCP Server” 输入此远程 MCP 服务 URL：[SERVER DECOMISSIONED - HOST YOUR OWN DEPLOYMENT AS DESCRIBED]

步骤 3：立即测试 试着提问：“查找 Frankfurt 附近的火车站，并查看 Frankfurt Hauptbahnhof 当前是否有延误。”

📱 可尝试的快速示例

连接后，可以尝试以下实用示例：

🔍 车站搜索

• “查找 Munich 的所有火车站”
• “坐标 52.5200, 13.4050 周围 5 公里内有哪些车站？”

🚄 实时信息

• “Berlin Hauptbahnhof 现在有延误吗？”
• “显示今天下午 3 点 Hamburg Hbf 的出发时刻表”

♿ 无障碍出行规划

• “从 München 到 Hamburg 可以无障碍出行吗？”
• “Köln Hauptbahnhof 提供哪些无障碍服务？”

🅿️ 停车信息

• “明天上午 10 点 Frankfurt Hauptbahnhof 有哪些停车位？”
• “查找 Düsseldorf 主车站附近的停车场”

🗺️ 出行规划

• “帮我规划从 Berlin 到 Dresden 的无障碍出行路线”
• “Bavaria 有哪些主要铁路枢纽？”

🔧 连接故障排除

Claude Desktop 问题：

问题：MCP 部分未显示服务

• 验证配置文件中的 JSON 语法（使用 JSON 验证器）
• 确保已完全重启 Claude Desktop
• 检查文件是否保存在正确的位置

问题：连接超时

• 验证互联网连接
• 在终端中尝试：curl https://[SERVER DECOMISSIONED - HOST YOUR OWN DEPLOYMENT AS DESCRIBED]/mcp/ping
• 如果 curl 失败，可能存在网络限制

问题："Command not found" 错误

• 确保已安装 Node.js 和 npm
• 尝试运行：npm install -g mcp-remote

Claude.ai 网页版问题：

问题："Cannot connect to MCP server"

• 网页版可能需要明确支持 MCP 服务
• 尝试让 Claude 帮助你逐步连接
• 替代方案：使用特定工具调用，例如询问车站信息

常见问题：

服务状态检查：

# Test if server is responding
curl https://[SERVER DECOMISSIONED - HOST YOUR OWN DEPLOYMENT AS DESCRIBED]/health

# Test MCP endpoint
curl https://[SERVER DECOMISSIONED - HOST YOUR OWN DEPLOYMENT AS DESCRIBED]/mcp/ping

速率限制：

• 服务允许每分钟 60 次请求，每小时 1000 次
• 如果超出限制，请稍候再试
• 考虑使用特定查询，而不是宽泛搜索

🛠️ 可用功能

🔧 工具（13 个可用）

车站数据

• get_station_by_name(name, limit=10) - 按名称搜索车站，并使用备用筛选
• get_stations_by_position(lat, lon, radius=2.0) - 使用智能区域筛选查找附近车站

时刻表与运行中断

• get_planned_timetable(eva_number, date, hour) - 计划出发和到达信息
• get_recent_timetable_changes(eva_number) - 实时更新（最近 2 分钟）
• get_full_timetable_changes(eva_number) - 所有已知的未来运行中断

停车信息

• get_parking_by_station(stop_place_id) - 车站附近的停车设施
• search_parking_facilities(station_name) - 使用真实 API 按车站名称搜索停车设施
• get_parking_prognoses(facility_id, datetime) - 停车可用情况预测

无障碍服务

• find_facilities(station_number, type, state) - 电梯、自动扶梯状态
• get_facilities_by_station(station_number) - 完整的设施概览
• get_szentralen_by_location(lat, lon) - 使用区域筛选查找出行服务中心
• search_szentralen(limit, offset) - 支持分页的服务中心搜索

💬 交互式提示词（7 个可用）

• accessibility_check - 验证车站之间的无障碍出行情况
• parking_prognosis - 预测车站停车位的可用情况
• recent_timetable_changes - 实时延误和服务中断
• planned_timetable_window - 特定时间段的列车时刻表
• station_services - 完整的车站信息和设施
• nearby_stations - 查找地理坐标附近的铁路车站
• current_disruptions - 全面的服务中断概览

📚 参考资源（5 个可用）

• file://reference/station-categories - 德国铁路车站分类指南
• file://reference/train-types - 德国列车类型完整指南（ICE、IC、RE 等）
• file://stations/major-hubs - 德国最重要铁路车站列表
• file://services/accessibility-guide - 无障碍功能综合指南
• file://status/current-disruptions - 全系统运行中断概览

🏗️ 架构

├── main.py                    # FastAPI application entry point
├── server_instance.py         # Shared MCP server instance
├── mcp_server.py             # Server setup and module registration
├── utils.py                  # Shared utilities and validation
├── config.py                 # Configuration and secret management
├── models.py                 # Pydantic data models
├── rate_limiter.py           # Security: rate limiting
├── tools/                    # MCP Tools
│   ├── station_tools.py      # Station search and lookup
│   ├── timetable_tools.py    # Timetables and disruptions
│   ├── parking_tools.py      # Parking facilities
│   └── facility_tools.py     # Accessibility services
├── resources/                # MCP Resources
│   └── travel_resources.py   # Travel guides and references
└── prompts/                  # MCP Prompts
    └── travel_prompts.py      # Interactive travel assistance

🎯 智能地理筛选

该服务实现了智能区域筛选，以最大限度提高 API 效率和结果相关性：

坐标到区域的映射

• 联邦州检测：将坐标映射到德国联邦州（Bayern、Hessen 等）
• 边境区域处理：对于靠近边境的位置，包含邻近联邦州
• 按城市筛选：使用相关联邦州内的主要城市进行定向搜索

增强的车站搜索

• 区域预筛选：get_stations_by_position() 从相关联邦州获取车站，而不是随机获取 1000 个车站
• 回退机制：get_station_by_name() 使用 API 搜索字符串，并在客户端进行回退处理
• 距离计算：使用实际坐标进行精确的 haversine 距离计算

S-Zentralen 区域筛选

• 城市匹配：根据坐标确定的区域，按区域内的城市筛选 S-Zentralen
• 州与城市映射：全面映射联邦州与主要城市
• 相关结果：返回区域服务中心，而不是德国境内的所有服务中心

🔒 安全功能

• 速率限制：每个客户端每分钟 60 个请求、每小时 1000 个请求
• 输入验证：全面的清理与验证
• 安全标头：防范 XSS、CSRF，并提供内容类型保护
• 错误清理：不泄露敏感信息
• 仅限 HTTPS：安全传输层
• CORS 保护：受控的跨域访问

🚀 部署

Google Cloud Run（推荐）

按照以下步骤部署自己的 Deutsche Bahn MCP Server 实例：

前置条件

• 已安装并配置 Google Cloud CLI
• 从 developers.deutschebahn.com 获取的 Deutsche Bahn API 凭据

基本部署（默认 Cloud Run URL）

1. 设置密钥：

   # Create secrets for your DB API credentials
   echo "your_db_api_key" | gcloud secrets create DB_API_KEY --data-file=-
   echo "your_db_api_secret" | gcloud secrets create DB_API_SECRET --data-file=-
   

2. 部署服务：

   # Clone the repository
   git clone https://github.com/your-repo/deutsche-bahn-mcp-server
   cd deutsche-bahn-mcp-server
   
   # Deploy to Cloud Run
   gcloud run deploy deutschebahn-mcp-server \\
     --source . \\
     --region europe-west3 \\
     --allow-unauthenticated \\
     --port 8080
   

3. 授予密钥访问权限：

   # Get your service account email from the deployment output
   gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \\
     --member="serviceAccount:[email protected]" \\
     --role="roles/secretmanager.secretAccessor"
   

4. 使用 MCP 服务： 服务将在提供的 Cloud Run URL 上可用，例如： https://deutschebahn-mcp-server-123456789.region.run.app/mcp

自定义域名部署（生产环境）

在生产环境中使用自定义域名并增强安全性：

1. 按照上述基本部署步骤 1-3 操作

2. 设置自定义域名和负载均衡器（参见 Google Cloud Load Balancer 文档）

3. 使用自定义域名重新部署：

   gcloud run deploy deutschebahn-mcp-server \\
     --source . \\
     --region europe-west3 \\
     --allow-unauthenticated \\
     --port 8080 \\
     --set-env-vars CUSTOM_DOMAIN=your-domain.com
   

Docker（本地开发）

# Build the image
docker build -t deutschebahn-mcp-server .

# Run locally with your API credentials
docker run -p 8080:8080 \\
  -e DB_API_KEY=your_db_api_key \\
  -e DB_API_SECRET=your_db_api_secret \\
  deutschebahn-mcp-server

# Server available at http://localhost:8080/mcp

安全注意事项

• 默认部署：使用 Cloud Run 内置的 HTTPS，并允许通过生成的 URL 访问
• 自定义域名：仅允许访问指定域名，并阻止直接通过 Cloud Run URL 访问
• API 凭据：始终存储在 Google Secret Manager 中，绝不存储在环境变量或代码里
• 速率限制：内置保护（每个客户端每分钟 60 个请求、每小时 1000 个请求）

部署故障排查

Secret Manager 访问问题：

# Verify secrets exist
gcloud secrets list

# Check service account permissions
gcloud projects get-iam-policy YOUR_PROJECT_ID \\
  --flatten="bindings[].members" \\
  --filter="bindings.members:*gserviceaccount.com"

连接问题：

# Test your deployed service
curl https://your-service-url/health

# Check logs
gcloud run logs read --service=deutschebahn-mcp-server --region=your-region

📖 使用示例

智能地理位置车站搜索

# Ask Claude: "Find train stations near Munich city center"
# Uses: get_stations_by_position(48.1351, 11.5820) 
# → Smart regional filtering returns relevant Bavarian stations

增强的车站搜索

# Ask Claude: "Find train stations in Frankfurt"
# Uses: get_station_by_name("Frankfurt")
# → API searchstring parameter with intelligent fallback

区域服务中心

# Ask Claude: "Find mobility service centers near Berlin"
# Uses: get_szentralen_by_location(52.5200, 13.4050)
# → Returns Berlin/Brandenburg S-Zentralen using city filtering

实时运营中断信息

# Ask Claude: "Are there any delays at Berlin Hauptbahnhof?"
# Uses: recent_timetable_changes prompt

精确的停车搜索

# Ask Claude: "Find parking at Frankfurt Hauptbahnhof"
# Uses: search_parking_facilities("Frankfurt Hauptbahnhof")
# → Uses real API stationName parameter for accurate results

🧪 开发

运行测试

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Run with coverage
pytest --cov=. tests/

代码质量

# Format code
black .

# Lint code
flake8 .

# Type checking
mypy .

使用 MCP Inspector 进行本地测试

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Inspect local server
mcp-inspector http://localhost:8080/mcp

🤝 参与贡献

欢迎社区贡献！详细信息请参阅 CONTRIBUTING.md 指南。

贡献者快速入门

1. Fork 此代码库
2. 创建功能分支：git checkout -b feature-name
3. 编写代码并添加测试
4. 遵循我们的开发指南
5. 提交拉取请求

署名要求

如果你在自己的项目中使用本作品、代码或概念，请注明出处：

Based on Deutsche Bahn MCP Server by Paul von Berg
https://github.com/PaulvonBerg/db-mcp-server

谢谢！

⚙️ 配置

服务通过环境变量进行配置。在本地开发时，将 .env.example 模板复制到根目录并创建 .env 文件。在云端部署时，可通过 Google Secret Manager 设置这些值，也可以直接在服务上设置。

请参阅 .env.example 文件中的注释，了解各凭据的对应位置，避免混淆。

环境变量

变量	描述	来源 / 备注
DB_API_KEY	你的 Deutsche Bahn API Client ID	必需。本地设置在 .env 中，云端设置为 DB_API_KEY 密钥。
DB_API_SECRET	你的 Deutsche Bahn API Key (the secret)	必需。本地设置在 .env 中，云端设置为 DB_API_SECRET 密钥。
GCP_PROJECT_ID	你的 Google Cloud 项目 ID	云端部署时必需。若未设置，将自动检测。
CUSTOM_DOMAIN	已部署服务的自定义域名	可选。为云端部署启用增强安全性。
CLOUD_RUN_URL	Cloud Run 服务的后端 URL	可选。在 Cloud Run 中会自动检测，仅在需要时覆盖。
LOG_LEVEL	日志级别（DEBUG、INFO、WARNING、ERROR）	可选。默认为 INFO。
PORT	服务监听的端口	可选。默认为 8080。

📚 API 参考

使用的 Deutsche Bahn API

• StaDa API v2：站点主数据
• Timetables API v1：时刻表和运行中断数据
• Parking Information API v2：DB Bahnpark 设施
• FaSta API v2：设施状态（电梯、自动扶梯）

🐛 故障排除

常见问题

API 身份验证错误

• 确认 DB API 凭据正确
• 检查 API 密钥权限和配额

连接问题

• 确保服务在正确的端口上运行
• 确认防火墙设置允许连接
• 检查 Cloud Run 服务权限

MCP 客户端连接

• 确认 MCP 客户端配置语法正确
• 检查服务 URL 是否可访问
• 确保使用正确的传输模式（仅 http）

调试

启用调试日志：

export LOG_LEVEL=DEBUG
python main.py

📄 许可证

本项目依据 Creative Commons Attribution 4.0 International License (CC BY 4.0) 授权，详情请参阅 LICENSE 文件。

署名要求

使用本软件或数据时，必须适当注明以下来源：

• Deutsche Bahn AG：底层 API 和铁路数据（CC BY 4.0）
• 本 MCP 服务实现的贡献者

Deutsche Bahn API 合规性

本软件依据不同的许可条款访问 Deutsche Bahn 的公共 API：

• 大多数 API：CC BY 4.0（站点数据、时刻表、无障碍服务）
• 停车 API：„Datenlizenz Deutschland – Namensnennung – Version 2.0“（dl-de/by-2-0）

重要：停车信息数据有额外限制：

• 不允许修改内容
• 允许更改技术格式
• 必须注明特定来源：“Parking Information Daten der DB BahnPark – API über den DB API Marketplace”

用户必须遵守 Deutsche Bahn 在 developers.deutschebahn.com 上的 API 服务条款。

注意：本软件与 Deutsche Bahn AG 没有官方关联。

⚠️ 服务免责声明

面向使用 [SERVER DECOMISSIONED - HOST YOUR OWN DEPLOYMENT AS DESCRIBED] 上线服务的用户：

这是由社区独立托管的社区提供服务。请注意：

• 不保证正常运行时间——服务可能会在不另行通知的情况下不可用
• 适用速率限制——每个客户端每分钟 60 次请求，每小时 1000 次请求
• 数据准确性——信息按原样提供，来源为 Deutsche Bahn API
• 不承担责任——使用风险自负，且仅供参考
• 服务监控——出于运维目的，可能会记录使用情况
• 遵守条款——用户必须遵守 Deutsche Bahn API 条款

用于生产环境时，请考虑根据上述部署说明托管自己的实例。

托管方：本服务由独立开发者提供，与 Deutsche Bahn AG 无关联

🙏 致谢

• 感谢 Deutsche Bahn 提供公共 API
• 感谢 Anthropic 推出 Model Context Protocol
• 感谢 FastMCP 库提供 Python MCP 实现

---

线上服务：[SERVER DECOMISSIONED - HOST YOUR OWN DEPLOYMENT AS DESCRIBED]