Renfe MCP Server
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Renfe MCP ServerWhat trains go from Madrid to Barcelona tomorrow?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Renfe MCP Server ๐
A Model Context Protocol (MCP) server for querying Renfe (Spanish national railway) train schedules using official GTFS data. Integrates seamlessly with Claude Desktop and other MCP-compatible clients.
โจ 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
Related MCP server: railinfo-mcp
๐ Quick Start
Prerequisites
Python 3.12 or higher
uv (recommended) or pip
Installation
Clone the repository
git clone https://github.com/yourusername/renfe_mcp.git cd renfe_mcpInstall dependencies
uv syncRun the server (GTFS data downloads automatically)
uv run python -m renfe_mcp.server
๐ Usage
Standalone Testing
Test the search functionality directly:
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):
{
"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"
]
}
}
}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: 42. 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 assearch_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=2Note: 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:
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:
uv run python -m renfe_mcp.update_dataForce update (download regardless of version):
uv run python -m renfe_mcp.update_data --forceThe 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 trackingHow It Works
City to Station Mapping: Fuzzy matches city names to station IDs
Date Filtering:
Checks
calendar.txtfor service schedules (day of week)Applies exceptions from
calendar_dates.txt(holidays, special dates)
Route Finding:
Joins trips, stop_times, and stops tables
Validates stop sequences and pickup/dropoff permissions
Ensures origin comes before destination
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
# 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.pyDependencies
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:
# 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:
API Endpoint:
https://data.renfe.com/api/3/action/resource_showResource ID:
25d6b043-9e47-4f99-bd91-edd51d782450Update 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:
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
Ideas for Contributions
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 file for details.
๐ Acknowledgments
Renfe Operadora for providing open GTFS data
Anthropic for Claude and the Model Context Protocol
The GTFS community for standardizing transit data
๐ฎ Support
Issues: GitHub Issues
Discussions: GitHub Discussions
MCP Docs: Model Context Protocol
๐ Related Projects
SNCF MCP Server - Similar server for French railways
FastMCP - The framework powering this server
MCP Servers - Official MCP server implementations
๐ Sources & Inspiration
renfe-bot by @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 and Claude
Travel smart, travel by train! ๐
Available Tools
3 toolsfind_stationA
Search for train stations in a city and return matching options.
Useful for checking what stations are available in a city before searching for journeys.
Args: city_name: City name to search for (e.g., "Madrid", "Barcelona", "Valencia") api_key: API key for authentication (optional if configured via environment)
Returns: A formatted string showing all matching stations with their IDs and full names.
| Name | Required | Description | Default |
|---|---|---|---|
| city_name | Yes | ||
| api_key | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It mentions returns as a formatted string with IDs and names, and that api_key is optional. However, it does not disclose potential side effects, rate limits, or error behavior, which is a gap for a network call tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loading the purpose in the first sentence, followed by a clear use case and structured Args/Returns sections. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters and an output schema exists, the description provides all necessary context: what it does, when to use it, parameter explanations, and return format. It is complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully by explaining city_name with examples (e.g., Madrid, Barcelona) and clarifying api_key's optional nature and purpose. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Search for train stations in a city and return matching options.' It uses a specific verb (Search) and resource (stations), and clearly distinguishes from sibling tools like get_train_prices and search_trains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: 'Useful for checking what stations are available in a city before searching for journeys.' This explains when to use the tool, but does not explicitly state when not to use or mention alternatives beyond the implied sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_train_pricesA
Check actual ticket prices for trains between two cities using web scraping with pagination.
NOTE: This tool scrapes the Renfe website and may take a few seconds to complete. It complements the search_trains tool by providing real-time price information. This endpoint has stricter rate limits due to web scraping.
Args: origin: Starting city name (e.g., "Madrid", "Barcelona", "Valencia") destination: Destination city name (e.g., "Madrid", "Barcelona", "Sevilla") date: Travel date. Accepts flexible formats: - ISO: "2025-11-28" (RECOMMENDED) - European: "28/11/2025" - Written: "November 28, 2025" or "28 November 2025" If not provided, checks prices for today's date. page: Page number to display (default: 1) per_page: Number of results per page (default: 5, max: 20) api_key: API key for authentication (optional if configured via environment)
Returns: Formatted string with train prices, availability, and booking information.
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | ||
| destination | Yes | ||
| date | No | ||
| page | No | ||
| per_page | No | ||
| api_key | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses scraping behavior, potential delays, rate limits, pagination, and the return format, giving the agent clear behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args and Returns sections but is slightly verbose. However, it efficiently front-loads the purpose and provides necessary parameter details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and a missing output schema, the description comprehensively covers purpose, usage, behavior, and all parameters, leaving no critical gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description adds essential meaning to all 6 parameters, including examples for origin/destination, detailed date formats, page/per_page defaults, and api_key usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks actual ticket prices via web scraping with pagination, and distinguishes it from the sibling tool search_trains by noting it provides real-time price information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it complements search_trains and notes stricter rate limits, providing usage context. However, it does not explicitly state when not to use this tool or give alternatives beyond the sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_trainsA
Search for train journeys between two cities on a specific date.
Args: origin: Starting city name (e.g., "Madrid", "Barcelona", "Valencia") destination: Destination city name (e.g., "Madrid", "Barcelona", "Sevilla") date: Travel date. Accepts flexible formats: - ISO: "2025-11-28" (RECOMMENDED) - European: "28/11/2025" - Written: "November 28, 2025" or "28 November 2025" If not provided, searches for today's date. page: Page number to display (default: 1) per_page: Number of results per page (default: 10, max: 50) api_key: API key for authentication (optional if configured via environment)
Returns: Formatted string with available train options including times and durations.
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | ||
| destination | Yes | ||
| date | No | ||
| page | No | ||
| per_page | No | ||
| api_key | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes input parameters and output (formatted string with times/durations), but lacks details on side effects, authentication (api_key optional but not explained), rate limits, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Args' and 'Returns' sections, each parameter is clearly described, and the entire text is concise without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters (2 required) and no annotations, the description covers all parameters and explains the return value (formatted string). However, it could include more detail on pagination behavior or error responses, and the output schema exists but is not summarized in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description adds substantial meaning: lists example city names for origin/destination, explains flexible date formats, specifies default and max values for page/per_page, and clarifies api_key as optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for train journeys between two cities on a specific date, using the verb 'Search' and resource 'train journeys'. It distinguishes from siblings 'find_station' and 'get_train_prices' by focusing on journey search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (search for train journeys) and provides date format guidance. However, it does not explicitly state when not to use it or mention alternatives like 'get_train_prices' for pricing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
3 tool updates
v0.4.0- First observed
find_station - First observed
get_train_prices - First observed
search_trains
TDQS
Each tool serves a distinct purpose: station lookup, journey search, and price retrieval. No overlap in functionality.
All tools follow a consistent verb_noun pattern in snake_case: find_station, get_train_prices, search_trains.
Three tools cover the core workflow of finding stations, searching journeys, and checking prices. While minimal, it's appropriate for the scope.
Covers the essential travel information needs: station lookup, journey search, and pricing. Missing booking or detailed trip info, but acceptable for an info-focused server.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Provide detailed Pokรฉmon data and information through a standardized MCP interface. Enable LLMs anโฆ
Read-only public transit departures, stop search, and city coverage for bus and train users.
Search award flights and cash fares, optimize points, and predict fares inside ChatGPT and Claude.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides real-time Dutch Railways (NS) data for journey planning, live departures, disruptions, and station search.3-
- FlicenseNot gradedqualityDmaintenanceEnables real-time Indian Railways information retrieval, including live train running status, station schedules, and upcoming arrivals/departures.-
- FlicenseAqualityDmaintenanceEnables querying SNCF train schedules and stations in France using the official Navitia API, with support for flexible date parsing and real-time journey planning.31-
- AlicenseNot gradedqualityCmaintenanceEnables querying SNCF Open Data (train schedules, stations, punctuality, etc.) through natural language or direct tool calls, with dataset search, metadata retrieval, and ODSQL querying.15MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/belgrano9/renfe_mcp_server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server