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 包管理器）

第一步：克隆仓库

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

第二步：安装依赖

#1

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

#2

## 获取 API 密钥

在使用此服务器之前，您需要从 SNCF 获取一个 API 密钥：

1. 访问 [SNCF API 门户](https://www.digital.sncf.com/startup/api)
2. 创建账户或登录
3. 订阅 "Navitia" API 服务
4. 完成注册过程
5. 一旦被批准，您将在账户仪表板中收到您的 API 密钥

API 密钥看起来像一个 UUID 字符串（例如，`01293485-3NS3-3242-23AZ-3241324512`）。

## 配置

### 设置 Claude 桌面版

要将 SNCF MCP 工具与 Claude 桌面版集成：

1. **安装 Claude 桌面版**（如果您还没有安装的话）
2. **打开 Claude 桌面配置**：
   - 导航到 Claude 桌面设置
   - 打开配置文件（通常位于 `%APPDATA%\Claude\claude_desktop_config.json`）

#3

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

3. **保存配置文件** 并重启 Claude 桌面版

## 可用的 MCP 工具

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

### 路程规划

#### `plan_journey_by_city_names`

规划法国境内两个城市之间的旅程。

**参数：**
- `from_city`: 出发城市名称（例如，“巴黎”）
- `to_city`: 目的城市名称（例如，“马赛”）
- `datetime`: 可选的出发或到达时间（格式：YYYYMMDDTHHMMSS）
- `datetime_represents`: “departure” 或 “arrival”（默认：“departure”）
- `include_station_details`: 是否包含详细的车站信息

**示例提示给 Claude:**

#4

### 车站信息

#### `get_station_details`

获取城市内火车站点的详细信息。

**参数：**
- `city_name`: 要搜索车站的城市名称
- `station_name`: 可选的具体车站名称
- `station_id`: 可选的直接车站 ID
- `include_transport_types`: 是否包含交通类型分析
- `include_nearby_places`: 是否包含附近地点信息
- `nearby_distance`: 附近地点搜索半径（米）
- `nearby_count`: 返回的最大附近地点数量

**示例提示给 Claude:**

#5

#### `get_station_schedule`

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

**参数：**
- `city_name`: 要搜索车站的城市名称
- `station_name`: 可选的具体车站名称
- `station_id`: 可选的直接车站 ID
- `count`: 要返回的出发/到达次数
- `datetime`: 可选的起始时间
- `duration`: 可选的持续时间（秒）
- `data_freshness`: 数据新鲜度级别（实时或基本时刻表）

**示例提示给 Claude:**

#6

### 中断监控

#### `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. 从波尔多出发的即将发车的信息
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 服务器！请随时提交拉取请求或为错误和功能请求打开问题。

许可证

本项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

致谢

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

由 Christian delage (dr.christian.delage@gmail.com) 创建