# Renfe MCP Server 🚄

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for querying **Renfe** (Spanish national railway) train schedules using official GTFS data. Integrates seamlessly with Claude Desktop and other MCP-compatible clients.

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-v0.7+-green.svg)](https://github.com/jlowin/fastmcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🔍 **Search trains** between any two Spanish cities on a specific date with pagination
- 💰 **Check prices** - real-time price scraping from Renfe website with pagination support
- 🚉 **Find stations** in any city (Madrid has 7 stations!)
- 📅 **Flexible date parsing** - accepts ISO, European, and written date formats
- 🔄 **Auto-updates** - automatically downloads latest GTFS schedules from Renfe
- ⚡ **Fast & accurate** - uses official Renfe GTFS data with complete timetables
- 🎯 **Smart filtering** - handles service calendars, holidays, and exceptions
- 🛠️ **Claude Desktop ready** - works out of the box with MCP clients

## 🚀 Quick Start

### Prerequisites

- Python 3.12 or higher
- [uv](https://github.com/astral-sh/uv) (recommended) or pip

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/yourusername/renfe_mcp.git
   cd renfe_mcp
   ```

2. **Install dependencies**
   ```bash
   uv sync
   ```

3. **Run the server** (GTFS data downloads automatically)
   ```bash
   uv run python -m renfe_mcp.server
   ```

## 📖 Usage

### Standalone Testing

Test the search functionality directly:

```python
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 Desktop Integration

Add to your Claude Desktop config file:

**Windows** (`%APPDATA%\Claude\claude_desktop_config.json`):
```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`):
```json
{
  "mcpServers": {
    "renfe": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/renfe_mcp",
        "run",
        "python",
        "-m",
        "renfe_mcp.server"
      ]
    }
  }
}
```

**Linux** (`~/.config/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "renfe": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/renfe_mcp",
        "run",
        "python",
        "-m",
        "renfe_mcp.server"
      ]
    }
  }
}
```

Restart Claude Desktop, and you can ask:
- *"Show me trains from Madrid to Barcelona tomorrow"*
- *"What's the earliest train from Barcelona to Valencia on December 1st?"*
- *"What train stations are in Madrid?"*
- *"How many trains run between Madrid and Sevilla in the afternoon?"*
- *"Check prices for trains from Madrid to Barcelona on December 1st"*
- *"What are the ticket prices for the first 5 trains?"*

## 🛠️ MCP Tools

### 1. `search_trains`

Find trains between two cities on a specific date with pagination support.

**Parameters:**
- `origin` (string): Origin city name (e.g., "Madrid", "Barcelona")
- `destination` (string): Destination city name (e.g., "Valencia", "Sevilla")
- `date` (string, optional): Travel date in flexible formats:
  - ISO: `"2025-11-28"`
  - European: `"28/11/2025"`
  - Written: `"November 28, 2025"`
  - Default: today's date
- `page` (integer, optional): Page number to display (default: 1)
- `per_page` (integer, optional): Results per page (default: 10, max: 50)

**Example Output:**
```
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`

Search for train stations in a city.

**Parameters:**
- `city_name` (string): City name to search (e.g., "Madrid")

**Example Output:**
```
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`

Check actual ticket prices by scraping the Renfe website with pagination support.

**Parameters:**
- `origin` (string): Origin city name (e.g., "Madrid", "Barcelona")
- `destination` (string): Destination city name (e.g., "Valencia", "Sevilla")
- `date` (string, optional): Travel date (same formats as `search_trains`)
- `page` (integer, optional): Page number to display (default: 1)
- `per_page` (integer, optional): Results per page (default: 5, max: 20)

**Example Output:**
```
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
```

**Note:** This tool scrapes the Renfe website and may take a few seconds to complete. Pagination now matches `search_trains` so you can get prices for trains on any page (e.g., page 2 shows prices for trains 6-10).

## 📊 Data Updates

The server includes automatic GTFS data updates from Renfe's open data portal.

### Automatic Updates

On server startup, it checks for new data and downloads if needed:

```bash
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!
```

### Manual Updates

**Check and update if needed:**
```bash
uv run python -m renfe_mcp.update_data
```

**Force update (download regardless of version):**
```bash
uv run python -m renfe_mcp.update_data --force
```

The update system:
- ✅ Compares server version with local version
- ✅ Only downloads when new data is available
- ✅ Stores version info in `renfe_schedule/.last_updated`
- ✅ Automatically extracts GTFS CSV files

## 🏗️ Architecture

```
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
```

### How It Works

1. **City to Station Mapping**: Fuzzy matches city names to station IDs
2. **Date Filtering**:
   - Checks `calendar.txt` for service schedules (day of week)
   - Applies exceptions from `calendar_dates.txt` (holidays, special dates)
3. **Route Finding**:
   - Joins trips, stop_times, and stops tables
   - Validates stop sequences and pickup/dropoff permissions
   - Ensures origin comes before destination
4. **Results**: Returns all trains sorted chronologically with proper numeric time sorting

### Key Implementation Details

- ✅ Handles multiple stations per city (e.g., Madrid has 7)
- ✅ Respects service exceptions (holidays, maintenance)
- ✅ Validates passenger boarding/alighting permissions (`pickup_type`, `drop_off_type`)
- ✅ **Fixed sorting bug**: Proper numeric time sorting (not lexicographic!)
- ✅ CSV column whitespace handling (strips on load)
- ✅ Complete result sets (no truncation)

## 🗺️ Supported Routes

The server supports **any route** in the Renfe network:

- **High-Speed (AVE)**: Madrid-Barcelona, Madrid-Sevilla, Madrid-Valencia
- **Long-Distance (ALVIA, Intercity)**: Major city connections
- **International (AVE INT)**: Cross-border services
- **Regional**: Local routes across Spain
- **Commuter (Cercanías)**: Urban networks

**Popular Cities:**
- Madrid (7 stations), Barcelona, Valencia
- Sevilla, Málaga, Bilbao, Zaragoza
- Alicante, Córdoba, Granada, Murcia
- **100+ cities** across Spain!

Use `find_station` to discover available stations in any city.

## 🔧 Development

### Project Setup

```bash
# 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
```

### Dependencies

- **fastmcp** (>=0.7.0) - MCP server framework
- **pandas** (>=2.3.3) - GTFS data processing
- **pydantic** (>=2.11.7) - Data validation and models
- **pydantic-settings** (>=2.0.0) - Environment-based configuration
- **httpx** (>=0.27.0) - Modern HTTP client for price scraping
- **python-dateutil** (>=2.8.2) - Flexible date parsing
- **json5** (>=0.12.0) - JavaScript object parsing for DWR responses
- **python-dotenv** (>=1.0.0) - Environment variables

### Configuration

Configure via environment variables (prefix `RENFE_`) or `.env` file:

```bash
# 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
```

## 📝 Data Source

GTFS data from [Renfe's Open Data Portal](https://data.renfe.com):
- **API Endpoint**: `https://data.renfe.com/api/3/action/resource_show`
- **Resource ID**: `25d6b043-9e47-4f99-bd91-edd51d782450`
- **Update Frequency**: Updated regularly by Renfe (checked on server startup)
- **Format**: GTFS (General Transit Feed Specification)
- **Size**: ~800 KB compressed, ~40 MB extracted

## 🐛 Known Issues

- Windows console may show encoding errors with Unicode characters (functionality not affected)
- Very large result sets (100+ trains) can be verbose but complete

## 🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Ideas for Contributions

- [x] ~~Add price information~~ (✅ Implemented via web scraping)
- [ ] Support for train status/delays
- [ ] Multi-leg journey planning
- [ ] Visualization of routes on maps
- [ ] Additional query filters (train type, duration, etc.)
- [ ] Return trip price checking

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Renfe Operadora](https://www.renfe.com) for providing open GTFS data
- [FastMCP](https://github.com/jlowin/fastmcp) by [@jlowin](https://github.com/jlowin) for the excellent MCP framework
- [Anthropic](https://www.anthropic.com) for Claude and the Model Context Protocol
- The GTFS community for standardizing transit data

## 📮 Support

- **Issues**: [GitHub Issues](https://github.com/belgrano9/renfe_mcp_server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/belgrano9/renfe_mcp_server/discussions)
- **MCP Docs**: [Model Context Protocol](https://modelcontextprotocol.io)

## 🔗 Related Projects

- [SNCF MCP Server](https://github.com/belgrano9/sncf_mcp_server) - Similar server for French railways
- [FastMCP](https://github.com/jlowin/fastmcp) - The framework powering this server
- [MCP Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations

## 🙏 Sources & Inspiration

- **[renfe-bot](https://github.com/emartinez-dev/renfe-bot)** by [@emartinez-dev](https://github.com/emartinez-dev) - Telegram bot for Renfe train ticket monitoring. The DWR (Direct Web Remoting) protocol reverse-engineering and price scraping techniques were inspired by renfe-bot's implementation. This MCP server features a custom-built scraper using modern Python (httpx, pydantic) while preserving the core DWR protocol logic.

---

**Built with ❤️ using [FastMCP](https://github.com/jlowin/fastmcp) and [Claude](https://claude.ai)**

*Travel smart, travel by train! 🚄*