使用说明

Renfe MCP服务器🚄

A. 模型上下文协议（MCP）查询服务器 Renfe （西班牙国家铁路）列车时刻表使用官方GTFS数据。与Claude Desktop和其他MCP兼容客户端无缝集成。

✨ 特性

🔍 搜索火车 在特定日期的任意两个西班牙城市之间进行分页
💰 查看价格 -支持分页的Renfe网站实时价格抓取
🚉 查找车站 在任何城市（马德里有7个车站！）
📅 灵活的日期解析 -接受ISO、欧洲和书面日期格式
🔄 自动更新 -自动从Renfe下载最新的GTFS时间表
⚡ 快速准确 -使用Renfe GTFS官方数据和完整时间表
🎯 智能过滤 -处理服务日历、假期和异常
🛠️ 克劳德桌面就绪 -与MCP客户端开箱即用

🚀 快速开始

先决条件

Python 3.12或更高版本
紫外线（推荐）或pip

安装

克隆存储库

git clone https://github.com/yourusername/renfe_mcp.git
cd renfe_mcp

安装依赖项
```
uv sync
```
运行服务器 （GTFS数据自动下载）
```
uv run python -m renfe_mcp.server
```

📖 用法

独立测试

直接测试搜索功能：

from renfe_mcp.schedule_searcher import ScheduleSearcher
from renfe_mcp.price_checker import check_prices

# Search trains
searcher = ScheduleSearcher("renfe_schedule")
trains = searcher.search("Madrid", "Barcelona", "2025-11-20")

# Check prices
prices = check_prices("Madrid", "Barcelona", "2025-11-20")

Claude桌面集成

添加到您的Claude Desktop配置文件中：

视窗 (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "renfe": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\YourName\\path\\to\\renfe_mcp",
        "run",
        "python",
        "-m",
        "renfe_mcp.server"
      ]
    }
  }
}

macOS (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "renfe": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/renfe_mcp",
        "run",
        "python",
        "-m",
        "renfe_mcp.server"
      ]
    }
  }
}

Linux (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "renfe": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/renfe_mcp",
        "run",
        "python",
        "-m",
        "renfe_mcp.server"
      ]
    }
  }
}

重新启动Claude Desktop，您可以问：

“明天给我看从马德里到巴塞罗那的火车”
“12月1日从巴塞罗那到瓦伦西亚最早的火车是几班？”
“马德里有哪些火车站？”
“下午马德里和塞维利亚之间有多少列火车？”
“查看12月1日从马德里到巴塞罗那的火车价格”
“前五班火车的票价是多少？”

🛠️ MCP工具

1. `search_trains`

使用分页支持查找特定日期两个城市之间的列车。

参数：

origin （string）：起源城市名称（例如“马德里”、“巴塞罗那”）
destination （string）：目的地城市名称（例如“瓦伦西亚”、“塞维利亚”）
date （字符串，可选）：灵活格式的旅行日期：
- ISO： "2025-11-28"
- 欧洲的： "28/11/2025"
- 书面： "November 28, 2025"
- 默认值：今天的日期
page （整数，可选）：要显示的页码（默认值：1）
per_page （整数，可选）：每页结果（默认值：10，最大值：50）

输出示例：

Found 36 train(s) total
Showing page 1 of 4 (10 trains)

  1. AVE
     Madrid Pta.Atocha - Almudena Grandes → Barcelona-Sants
     Departs: 6:16:00 | Arrives: 9:05:00
     Duration: 2h 49min

  2. AVE
     Madrid Pta.Atocha - Almudena Grandes → Barcelona-Sants
     Departs: 6:27:00 | Arrives: 9:25:00
     Duration: 2h 58min
  ...

─────────────────────────────────
To see more trains, use page=2
Total pages: 4

2. `find_station`

在城市中寻找火车站。

参数：

city_name （string）：要搜索的城市名称（例如“马德里”）

输出示例：

Found 7 stations:

All stations found:
  1. Madrid-Chamartín-Clara Campoamor (ID: 17000)
  2. Madrid - Atocha Cercanías (ID: 18000)
  3. Madrid Pta.Atocha - Almudena Grandes (ID: 60000)
  ...

3. `get_train_prices`

通过抓取支持分页的Renfe网站来查看实际票价。

参数：

origin （string）：起源城市名称（例如“马德里”、“巴塞罗那”）
destination （string）：目的地城市名称（例如“瓦伦西亚”、“塞维利亚”）
date （字符串，可选）：旅行日期（格式与 search_trains)
page （整数，可选）：要显示的页码（默认值：1）
per_page （整数，可选）：每页结果数（默认值：5，最大值：20）

输出示例：

PRICE CHECK RESULTS
From: Madrid -> Barcelona
Date: 2025-11-17
Showing 5 train(s)

  1. AVE
     Departs: 06:16 | Arrives: 09:05
     Duration: 2h 49min
     Price: 94.90 EUR | [Available]

  2. AVE
     Departs: 06:27 | Arrives: 09:25
     Duration: 2h 58min
     Price: 118.60 EUR | [Available]
  ...

To see more prices, try page=2

注：此工具会抓取Renfe网站，可能需要几秒钟才能完成。分页现在匹配 search_trains 因此，您可以在任何页面上获取列车价格（例如，第2页显示了6-10列列车的价格）。

📊 数据更新

该服务器包括来自Renfe开放数据门户的自动GTFS数据更新。

自动更新

在服务器启动时，它会检查新数据，并在需要时下载：

uv run python -m renfe_mcp.server
# [CHECK] Checking data versions:
#         Server: 2025-11-15T00:40:21
#         Local:  2025-11-10T00:30:15
# [UPDATE] Server has newer data
# [DOWNLOAD] Downloading GTFS data...
# [OK] GTFS data updated successfully!

手动更新

检查并更新（如果需要）：

uv run python -m renfe_mcp.update_data

强制更新（无论版本如何下载）：

uv run python -m renfe_mcp.update_data --force

更新系统：

✅ 将服务器版本与本地版本进行比较
✅ 仅在有新数据可用时下载
✅ 将版本信息存储在 renfe_schedule/.last_updated
✅ 自动提取GTFS CSV文件

🏗️ 建筑

renfe_mcp/
├── pyproject.toml           # Dependencies & build config
├── README.md                # This file
├── src/renfe_mcp/           # Main package
│   ├── __init__.py          # Package exports
│   ├── server.py            # FastMCP server implementation
│   ├── config.py            # Pydantic configuration
│   ├── exceptions.py        # Exception hierarchy
│   ├── logging.py           # Structured logging
│   ├── security.py          # Auth & rate limiting
│   ├── price_checker.py     # Price checking module
│   ├── schedule_searcher.py # GTFS schedule search
│   ├── station_service.py   # Unified station lookups
│   ├── update_data.py       # GTFS data updater
│   └── scraper/             # Price scraper package
│       ├── __init__.py      # Package exports
│       ├── scraper.py       # RenfeScraper with DWR protocol
│       ├── dwr.py           # DWR utilities
│       ├── models.py        # Pydantic models
│       ├── exceptions.py    # Scraper exceptions
│       └── stations.json    # Station code database
├── tests/                   # Test suite
│   ├── test_final_integration.py
│   ├── test_security.py
│   └── ...
└── renfe_schedule/          # GTFS data (auto-downloaded)
    ├── stops.txt            # Station information
    ├── routes.txt           # Train routes
    ├── trips.txt            # Trip schedules
    ├── stop_times.txt       # Arrival/departure times
    ├── calendar.txt         # Service schedules
    ├── calendar_dates.txt   # Holiday exceptions
    └── .last_updated        # Version tracking

运作原理

城市到车站地图：模糊匹配城市名称和车站ID
日期筛选:
- 检查 calendar.txt 服务时间表（星期几）
- 适用以下例外情况 calendar_dates.txt （节假日、特殊日期）
路线查找:
- 加入行程、停车时间和停车表
- 验证停车顺序和接送权限
- 确保出发地先于目的地
结果：返回按时间顺序排序的所有列车，并使用适当的数字时间排序

关键实施细节

✅ 每个城市处理多个车站（例如，马德里有7个）
✅ 尊重服务例外（节假日、维护）
✅ 验证乘客上下车权限(pickup_type, drop_off_type)
✅ 修复排序错误：正确的数字时间排序（不是字典排序！）
✅ CSV列空白处理（加载条带）
✅ 完整的结果集（无截断）

🗺️ 支持的路线

服务器支持 任何路线 在Renfe网络中：

高速（AVE）：马德里巴塞罗那、马德里塞维利亚、马德里瓦伦西亚
长途（ALVIA、城际）：主要城市连接
国际（AVE INT）：跨境服务
区域：西班牙各地的当地路线
通勤者（附近）：城市网络

热门城市：

马德里（7站）、巴塞罗那、瓦伦西亚
塞维利亚、马拉加、毕尔巴鄂、萨拉戈萨
阿利坎特、科尔多瓦、格拉纳达、穆尔西亚
100+城市 横跨西班牙！

使用 find_station 发现任何城市的可用车站。

🔧 发展

项目设置

# Clone and install
git clone https://github.com/yourusername/renfe_mcp.git
cd renfe_mcp
uv sync

# Run the server
uv run python -m renfe_mcp.server

# Run tests
uv run python tests/test_final_integration.py

依赖项

fastmcp （>=0.7.0）-MCP服务器框架
熊猫（>=2.3.3）-GTFS数据处理
皮丹提克 （>=2.11.7）-数据验证和模型
媒染剂设置 （>=2.0.0）-基于环境的配置
HTTPX （>=0.27.0）-用于价格抓取的现代HTTP客户端
python日期工具 （>=2.8.2）-灵活的日期解析
json5 （>=0.12.0）-DWR响应的JavaScript对象解析
python dotenv （>=1.0.0）-环境变量

配置

通过环境变量（前缀）进行配置 RENFE_)或 .env 文件：

# Authentication
RENFE_ENABLE_AUTH=true
RENFE_API_KEY=your-secret-key

# Rate Limiting
RENFE_RATE_LIMIT_ENABLED=true
RENFE_MAX_REQUESTS_PER_MINUTE=30
RENFE_MAX_REQUESTS_PER_HOUR=200

# Development
RENFE_DEV_MODE=false
RENFE_LOG_LEVEL=INFO

📝 数据源

GTFS数据来自 Renfe的开放数据门户:

API端点: https://data.renfe.com/api/3/action/resource_show
资源ID: 25d6b043-9e47-4f99-bd91-edd51d782450
更新频率：Renfe定期更新（在服务器启动时检查）
格式：GTFS（通用运输馈电规范）
尺寸：压缩约800 KB，提取约40 MB

🐛 已知问题

Windows控制台可能显示Unicode字符的编码错误（功能不受影响）
非常大的结果集（100多个序列）可能很冗长，但很完整

🤝 贡献

欢迎投稿！拜托：

复刻仓库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

贡献的想法

[x] ~~添加价格信息~~(✅ 通过网页抓取实现）
[]支持列车状态/延误
[]多段行程规划
[]地图上路线的可视化
[]其他查询筛选器（列车类型、持续时间等）
[]回程价格查询

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

Renfe 运营商用于提供开放的GTFS数据
FastMCP 通过 @杰洛温优秀的MCP框架
Anthropic 克劳德和模型上下文协议
GTFS社区用于标准化交通数据

📮 支持

问题: GitHub问题
讨论: GitHub讨论
MCP文件: 模型上下文协议

🔗 相关项目

SNCF MCP服务器 -法国铁路的类似服务器
FastMCP -支持此服务器的框架
MCP服务器 -官方MCP服务器实施

🙏 来源与灵感

renfe机器人 通过 @emartinez dev -用于Renfe火车票监控的Telegram机器人。DWR（Direct Web Remoting）协议逆向工程和价格抓取技术的灵感来自Renfe机器人的实现。此MCP服务器具有使用现代Python（httpx、pydantic）定制的scraper，同时保留了核心DWR协议逻辑。

内置于❤️ 使用 FastMCP 和克劳德

聪明旅行，坐火车旅行！ 🚄

使用说明

Renfe MCP服务器🚄

✨ 特性

🚀 快速开始

先决条件

安装

📖 用法

独立测试

Claude桌面集成

🛠️ MCP工具

1. search_trains

2. find_station

3. get_train_prices

📊 数据更新

自动更新

手动更新

🏗️ 建筑

运作原理

关键实施细节

🗺️ 支持的路线

🔧 发展

项目设置

依赖项

配置

📝 数据源

🐛 已知问题

🤝 贡献

贡献的想法

📄 许可证

🙏 致谢

📮 支持

🔗 相关项目

🙏 来源与灵感

相关 MCP

列车时刻查询服务器

荷兰铁路信息服务器

天气与铁路信息服务

百度地图

地图服务接口

滴滴出行MCP服务

1. `search_trains`

2. `find_station`

3. `get_train_prices`