SNCF API MCP Server

SNCF API MCP 服务

本项目提供了一个模块化的 Python 封装，用于调用 SNCF API，并通过 MCP 服务接口与 Claude Desktop 无缝集成，实现法国境内的智能行程规划和列车信息检索。

目录

• 概览
• 功能
• 安装
• 获取 API 密钥
• 配置
  • 设置 Claude Desktop
  • 环境变量
• 可用的 MCP 工具
  • 行程规划
  • 车站信息
  • 服务中断监控
• 使用示例
• 故障排除
• 高级功能

概览

SNCF MCP 服务提供了一个全面的接口，用于调用法国国家铁路公司（SNCF）的 API 服务，让你能够：

• 规划法国城市之间的列车行程
• 获取车站的详细信息
• 查询出发和到达时刻表
• 监控服务中断情况
• 查找附近地点和交通方式

项目结构如下：

• sncf_api/ - 用于调用 SNCF API 的主要软件包
  • __init__.py - 软件包初始化文件
  • config.py - 配置设置
  • client.py - 基础 API 客户端
  • api.py - 整合所有模块的主要 API 接口
  • search.py - 搜索相关端点
  • journey.py - 行程规划端点
  • stations.py - 车站相关端点
  • networks.py - 网络和交通方式端点
  • disruptions.py - 服务中断相关端点
  • station_finder.py - 按坐标高效查找车站
  • csv_station_finder.py - 使用 CSV 数据库查找车站
  • vehicle_journey.py - 列车行程详细信息
• sncf_server.py - 包含所有工具端点的 MCP 服务实现
• train_stations_europe.csv - 包含欧洲车站坐标的数据库

功能

• 智能行程规划：规划法国任意城市之间的行程，并自动选择车站
• 全面的车站详情：获取车站详细信息，包括：
  • 可用的交通类型（列车、巴士、有轨电车）
  • 附近地点和兴趣点
  • 坐标和无障碍设施信息
• 实时班次：获取最新的出发和到达信息
• 服务中断监控：及时了解服务中断情况
• 智能车站查找：按城市名称、车站名称或坐标查找车站
• 备用机制：主要城市的硬编码坐标可在 API 搜索失败时确保可靠性
• 详细日志记录：提供全面的日志记录，便于调试和监控

安装

先决条件

• Python 3.6+
• pip（Python 软件包管理器）

步骤 1：克隆代码库

git clone https://github.com/yourusername/sncf-mcp-new.git
cd sncf-mcp-new

步骤 2：安装依赖项

pip install -r requirements.txt

如果缺少 requirements.txt 文件，请安装以下软件包： requests mcp

pip install requests pandas mcp

获取 API 密钥

使用此服务前，你需要从 SNCF 获取 API 密钥：

1. 访问 SNCF API Portal
2. 创建账户或登录
3. 订阅“Navitia”API 服务
4. 完成注册流程
5. 审核通过后，你会在账户面板中收到 API 密钥

API 密钥的格式为 UUID 字符串（例如：01293485-3NS3-3242-23AZ-3241324512）。

配置

设置 Claude Desktop

要将 SNCF MCP 工具集成到 Claude Desktop 中：

1. 安装 Claude Desktop（如果尚未安装）
2. 打开 Claude Desktop 配置：
   • 前往 Claude Desktop 设置
   • 打开配置文件（通常位于 %APPDATA%\Claude\claude_desktop_config.json）

{
 "sncf": {
  "command": "py",
  "args": [
    "c:\\Users\\ChristianELHAJJ\\sncf-mcp-new\\sncf_server.py",
    "--api-key={YOUR-API-KEY}"
  ],
  "cwd": "c:\\Users\\ChristianELHAJJ\\sncf-mcp-new"
},

将 path/to/sncf-mcp-new 替换为实际的安装目录路径。

3. 保存配置文件并重启 Claude Desktop

可用的 MCP 工具

配置完成后，Claude Desktop 将可以使用以下工具：

行程规划

plan_journey_by_city_names

规划法国任意两座城市之间的行程。

参数：

• from_city：出发城市名称（例如，“Paris”）
• to_city：目的地城市名称（例如，“Marseille”）
• datetime：可选的出发或到达时间（格式：YYYYMMDDTHHMMSS）
• datetime_represents：“departure”或“arrival”（默认为“departure”）
• include_station_details：是否包含详细的车站信息

Claude 提示词示例：

Plan a train journey from Paris to Lyon tomorrow morning at 8 AM.

车站信息

get_station_details

获取某个城市火车站的全面详情。

参数：

• city_name：要搜索车站的城市名称
• station_name：可选的特定车站名称
• station_id：可选的直接车站 ID
• include_transport_types：是否包含交通类型分析
• include_nearby_places：是否包含附近地点信息
• nearby_distance：搜索附近地点的半径，单位为米
• nearby_count：要返回的附近地点数量上限

Claude 提示词示例：

What transport options are available at the main train station in Grenoble?

get_station_schedule

获取车站的出发和到达时刻表。

参数：

• city_name：要搜索车站的城市名称
• station_name：可选的特定车站名称
• station_id：可选的直接车站 ID
• count：要返回的出发/到达班次数量
• datetime：可选的起始日期和时间
• duration：可选的时长，单位为秒
• data_freshness：数据时效级别（realtime 或 base_schedule）

Claude 提示词示例：

Show me the next 5 train departures from Paris Gare de Lyon.

运营中断监控

check_disruptions

检查 SNCF 交通网络当前是否存在运营中断。

参数：

• coverage：覆盖区域（默认为“sncf”）
• count：要返回的运营中断数量上限
• station_id：可选的特定车站筛选条件
• line_id：可选的特定线路筛选条件
• since：仅显示此日期之后生效的运营中断
• until：仅显示此日期之前生效的运营中断
• fetch_train_details：是否获取受影响列车的更多详情

Claude 提示词示例：

Are there any current disruptions affecting trains to Marseille?

使用示例

规划行程

你可以让 Claude 规划法国任意两座城市之间的行程：

I need to travel from Paris to Nice next Friday at 2 PM. Can you find me a train?

Claude 将使用 plan_journey_by_city_names 工具来：

1. 找出两座城市的主要车站
2. 规划两地之间的最佳行程
3. 向你提供出发/到达时间、行程时长和换乘详情

获取车站信息

要获取车站的详细信息：

What facilities and transport options are available at Gare de Lyon in Paris?

Claude 将使用 get_station_details 工具提供：

1. 车站基本信息（名称、ID、坐标）
2. 可用的交通类型（火车、公交车、有轨电车）
3. 附近地点和兴趣点

查询列车时刻表

要查询即将出发或到达的列车：

When are the next trains leaving from Bordeaux to Paris today?

Claude 将使用 get_station_schedule 工具显示：

1. 从 Bordeaux 出发的即将发车信息
2. 目的地信息
3. 可用时的平台信息
4. 实时状态更新

监控运营中断

要查询服务中断情况：

Are there any disruptions affecting the Paris to Lyon route today?

Claude 将使用 check_disruptions 工具来：

1. 查找相关运营中断
2. 说明对服务的影响
3. 提供受影响列车的更多详情

故障排除

常见问题

“未提供 API 密钥”

• 确保已将 SNCF API 密钥添加到 Claude Desktop 配置中
• 检查 MCP 服务配置中是否正确引用了环境变量

“未找到该城市的车站”

• 尝试使用更具体的城市名称
• 对于较小的城市，尝试使用附近较大城市的名称
• 系统为法国主要城市硬编码了坐标，应能稳定使用

“无法连接到 SNCF API”

• 检查互联网连接
• 确认 API 密钥有效且未过期
• SNCF API 可能暂时无法使用；请稍后重试

“初始化 CSV 车站查找器时出错”

• 确保 train_stations_europe.csv 文件位于正确位置
• 检查文件权限，确保文件可读取

高级功能

硬编码坐标

系统为法国主要城市硬编码了坐标，即使 API 搜索失败，也能确保可靠性：

• 巴黎（48.853, 2.348）
• 马赛（43.303, 5.380）
• 里昂（45.760, 4.860）
• 图卢兹（43.611, 1.454）
• 尼斯（43.704, 7.262）
• 南特（47.217, -1.542）
• 斯特拉斯堡（48.585, 7.735）
• 波尔多（44.826, -0.556）
• 里尔（50.638, 3.072）
• 雷恩（48.103, -1.672）
• 格勒诺布尔（45.192, 5.716）

交通类型分析

get_station_details 工具可以分析并归类车站提供的交通类型：

• 长途列车（TGV、Intercités）
• 区域列车（TER）
• 本地交通（公交车、有轨电车、地铁）
• 其他服务（出租车、自行车共享）

搜索附近地点

车站详情工具可以查找车站附近的兴趣点：

• 其他交通站点
• 公共设施
• 兴趣点
• 地址点

此功能对规划从车站出发的后续行程的旅客尤其有用。

---

贡献

欢迎为改进 SNCF MCP Server 做出贡献！欢迎提交拉取请求，或针对错误和功能需求提出问题。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

• 感谢 SNCF 提供 API
• 感谢 Navitia 团队提供全面的公共交通 API
• 感谢 Claude AI 提供智能集成能力

由 Christian delage ([email protected]) 创建