SNCF API MCP Server
This project provides a modular Python wrapper for the SNCF API, with an MCP server interface that integrates seamlessly with Claude Desktop for intelligent journey planning and train information retrieval across France.
Table of Contents
- Overview
- Features
- Installation
- Getting an API Key
- Configuration
- Available MCP Tools
- Usage Examples
- Troubleshooting
- Advanced Features
Overview
The SNCF MCP Server provides a comprehensive interface to the French National Railway's (SNCF) API services, allowing you to:
- Plan train journeys between cities in France
- Get detailed information about train stations
- Check schedules for departures and arrivals
- Monitor service disruptions
- Find nearby places and transport options
The structure is organized as follows:
sncf_api/- The main package for SNCF API interaction__init__.py- Package initializationconfig.py- Configuration settingsclient.py- Base API clientapi.py- Main API interface combining all modulessearch.py- Search-related endpointsjourney.py- Journey planning endpointsstations.py- Station-related endpointsnetworks.py- Network and transport mode endpointsdisruptions.py- Disruption-related endpointsstation_finder.py- Efficient station lookup by coordinatescsv_station_finder.py- Station lookup using CSV databasevehicle_journey.py- Detailed train journey information
sncf_server.py- MCP server implementation with all tool endpointstrain_stations_europe.csv- Database of European train stations with coordinates
Features
- Intelligent Journey Planning: Plan trips between any cities in France with automatic station selection
- Comprehensive Station Details: Get detailed information about stations including:
- Available transport types (trains, buses, trams)
- Nearby places and points of interest
- Coordinates and accessibility information
- Real-time Schedules: Access up-to-date departure and arrival information
- Disruption Monitoring: Stay informed about service disruptions
- Smart Station Finding: Locate stations by city name, station name, or coordinates
- Fallback Mechanisms: Hardcoded coordinates for major cities ensure reliability even when API searches fail
- Detailed Logging: Comprehensive logging for debugging and monitoring
Installation
Prerequisites
- Python 3.6+
- pip (Python package manager)
Step 1: Clone the Repository
git clone https://github.com/yourusername/sncf-mcp-new.git
cd sncf-mcp-new
Step 2: Install Dependencies
pip install -r requirements.txt
If the requirements.txt file is missing, install the following packages: requests mcp
pip install requests pandas mcp
Getting an API Key
Before using this server, you need to obtain an API key from SNCF:
- Visit the SNCF API Portal
- Create an account or log in
- Subscribe to the "Navitia" API service
- Complete the registration process
- Once approved, you'll receive your API key in your account dashboard
The API key looks like a UUID string (e.g., 01293485-3NS3-3242-23AZ-3241324512).
Configuration
Setting Up Claude Desktop
To integrate the SNCF MCP tools with Claude Desktop:
- Install Claude Desktop if you haven't already
- Open Claude Desktop Configuration:
- Navigate to the Claude Desktop settings
- Open the configuration file (usually located at
%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"
},
Replace path/to/sncf-mcp-new with the actual path to your installation directory.
- Save the Configuration File and restart Claude Desktop
Available MCP Tools
Once configured, the following tools will be available to Claude Desktop:
Journey Planning
plan_journey_by_city_names
Plan a journey between two cities in France.
Parameters:
from_city: Departure city name (e.g., "Paris")to_city: Destination city name (e.g., "Marseille")datetime: Optional departure or arrival time (format: YYYYMMDDTHHMMSS)datetime_represents: "departure" or "arrival" (default: "departure")include_station_details: Whether to include detailed station information
Example prompt for Claude:
Plan a train journey from Paris to Lyon tomorrow morning at 8 AM.
Station Information
get_station_details
Get comprehensive details about train stations in a city.
Parameters:
city_name: Name of the city to search for stationsstation_name: Optional specific station namestation_id: Optional direct station IDinclude_transport_types: Whether to include transport type analysisinclude_nearby_places: Whether to include nearby places informationnearby_distance: Search radius in meters for nearby placesnearby_count: Maximum number of nearby places to return
Example prompt for Claude:
What transport options are available at the main train station in Grenoble?
get_station_schedule
Get departure and arrival schedules for a station.
Parameters:
city_name: Name of the city to search for stationsstation_name: Optional specific station namestation_id: Optional direct station IDcount: Number of departures/arrivals to returndatetime: Optional datetime to start fromduration: Optional duration in secondsdata_freshness: Data freshness level (realtime or base_schedule)
Example prompt for Claude:
Show me the next 5 train departures from Paris Gare de Lyon.
Disruption Monitoring
check_disruptions
Check for current disruptions in the SNCF transport network.
Parameters:
coverage: The coverage area (default: "sncf")count: Maximum number of disruptions to returnstation_id: Optional filter for a specific stationline_id: Optional filter for a specific linesince: Only disruptions valid after this dateuntil: Only disruptions valid before this datefetch_train_details: Whether to fetch additional details about affected trains
Example prompt for Claude:
Are there any current disruptions affecting trains to Marseille?
Usage Examples
Planning a Journey
You can ask Claude to plan a journey between any two cities in France:
I need to travel from Paris to Nice next Friday at 2 PM. Can you find me a train?
Claude will use the plan_journey_by_city_names tool to:
- Find the main stations in both cities
- Plan the optimal journey between them
- Present you with departure/arrival times, durations, and connection details
Getting Station Information
To get detailed information about a station:
What facilities and transport options are available at Gare de Lyon in Paris?
Claude will use the get_station_details tool to provide:
- Basic station information (name, ID, coordinates)
- Available transport types (trains, buses, trams)
- Nearby places and points of interest
Checking Train Schedules
To check upcoming departures or arrivals:
When are the next trains leaving from Bordeaux to Paris today?
Claude will use the get_station_schedule tool to show:
- Upcoming departures from Bordeaux
- Destination information
- Platform details when available
- Real-time status updates
Monitoring Disruptions
To check for service disruptions:
Are there any disruptions affecting the Paris to Lyon route today?
Claude will use the check_disruptions tool to:
- Find relevant disruptions
- Explain the impact on services
- Provide additional details about affected trains
Troubleshooting
Common Issues
"No API key provided"
- Ensure you've added your SNCF API key to the Claude Desktop configuration
- Check that the environment variable is correctly referenced in the MCP server configuration
"No stations found for city"
- Try using a more specific city name
- For smaller cities, try using the name of a nearby larger city
- The system has hardcoded coordinates for major French cities which should work reliably
"Failed to connect to SNCF API"
- Check your internet connection
- Verify that your API key is valid and not expired
- The SNCF API may be experiencing downtime; try again later
"Error initializing CSV station finder"
- Ensure the train_stations_europe.csv file is in the correct location
- Check file permissions to ensure the file is readable
Advanced Features
Hardcoded Coordinates
The system includes hardcoded coordinates for major French cities to ensure reliability even when the API search fails:
- Paris (48.853, 2.348)
- Marseille (43.303, 5.380)
- Lyon (45.760, 4.860)
- Toulouse (43.611, 1.454)
- Nice (43.704, 7.262)
- Nantes (47.217, -1.542)
- Strasbourg (48.585, 7.735)
- Bordeaux (44.826, -0.556)
- Lille (50.638, 3.072)
- Rennes (48.103, -1.672)
- Grenoble (45.192, 5.716)
Transport Type Analysis
The get_station_details tool can analyze and categorize the types of transport available at a station:
- Long-distance trains (TGV, Intercités)
- Regional trains (TER)
- Local transit (buses, trams, metros)
- Other services (taxis, bike sharing)
Nearby Places Search
The station details tool can find points of interest near a station:
- Other transport stops
- Public facilities
- Points of interest
- Address points
This feature is particularly useful for travelers planning their onward journey from a station.
Contributing
Contributions to improve the SNCF MCP Server are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- SNCF for providing the API
- The Navitia team for their comprehensive public transport API
- Claude AI for intelligent integration capabilities
created by Christian delage (dr.christian.delage@gmail.com)