GTFS MCP Server
A Model Context Protocol (MCP) server for GTFS (General Transit Feed Specification) data with multi-feed support. Query transit data from multiple cities/regions through a unified interface.
Features
- ✅ Multi-feed architecture - Support multiple GTFS feeds (Madrid, Barcelona, Tenerife, etc.)
- ✅ Hybrid journey planning - Door-to-door routing with OpenRouteService + GTFS
- ✅ Enhanced transit queries - Station details, line paths, transfer discovery
- ✅ SQLite-powered - Fast local queries with full indexing
- ✅ SOLID principles - Clean, maintainable architecture
- ✅ Type-safe - Full TypeScript implementation
- ✅ MCP compliant - Works with any MCP-compatible client
Architecture
This server follows SOLID principles and clean architecture patterns:
- Single Responsibility: Each tool handler has one specific purpose
- Open/Closed: Easy to extend with new tools without modifying existing code
- Liskov Substitution: All tool handlers implement the same interface
- Interface Segregation: Minimal, focused interfaces
- Dependency Inversion: Core logic depends on abstractions, not implementations
Project Structure
maps-train/
├── databases/
│ ├── registry.db # Feed registry (future)
│ └── feeds/
│ └── madrid.db # Madrid Metro GTFS database
├── gtfs/
│ └── madrid/ # Madrid GTFS CSV files
│ ├── agency.txt
│ ├── routes.txt
│ ├── stops.txt
│ └── ...
├── src/
│ ├── index.ts # Main server entry point
│ ├── feeds/
│ │ ├── Feed.ts # Feed wrapper class
│ │ ├── FeedRegistry.ts # Multi-feed manager
│ │ └── FeedImporter.ts # GTFS CSV importer
│ ├── repositories/
│ │ ├── BaseRepository.ts
│ │ ├── StopsRepository.ts
│ │ ├── RoutesRepository.ts
│ │ └── ...
│ ├── services/
│ │ ├── StationService.ts
│ │ ├── LineService.ts
│ │ └── ScheduleService.ts
│ ├── tools/
│ │ ├── GetStopsHandler.ts
│ │ ├── GetRoutesHandler.ts
│ │ └── GetScheduleHandler.ts
│ └── types/
│ ├── FeedTypes.ts
│ └── ToolHandler.ts
└── feeds.config.json # Feed configuration
Setup
1. Install Dependencies
2. Download GTFS Data
Download GTFS feeds from Transit.land:
Madrid Metro:
mkdir -p gtfs/madrid
cd gtfs/madrid
# Download from Transit.land: https://www.transit.land/feeds/f-ezz-crtm
# Or use direct link (example):
curl -o gtfs.zip "https://crtm.maps.arcgis.com/sharing/rest/content/items/d739e5aeb9c246d78cc4be12e98d9d5a/data"
unzip gtfs.zip
rm gtfs.zip
cd ../..
Tenerife TITSA:
mkdir -p gtfs/tenerife
cd gtfs/tenerife
# Download from Transit.land: https://www.transit.land/feeds/f-eth-tenerife~titsa
# Or use the direct GTFS download link from the feed page
cd ../..
Finding More Feeds:
- Visit Transit.land
- Search for your city or transit agency
- Click on the feed to get download links
- Download the GTFS zip file and extract to
gtfs/<feed_id>/
3. Configure Environment (Optional)
For journey planning with walking directions:
# Copy example and add your OpenRouteService API key
cp .env.example .env
# Edit .env and add your key
Get a free API key at OpenRouteService. All other tools work without any API keys.
4. Import GTFS Data
# Import Madrid Metro data
npm run import madrid
# Import other feeds (after adding to feeds.config.json)
npm run import tenerife
5. Build the Server
6. Start the Server
Development
npm run build - Compile TypeScript to JavaScript
npm run watch - Watch mode for development
npm run dev - Build and run the server
npm run import <feed_id> - Import a GTFS feed
Available Tools
Core GTFS Tools
1. get_stops - Get GTFS Stops/Stations
Search for transit stations by name, location, or route.
Parameters:
feed_id (optional) - Feed ID (madrid, barcelona, etc.). Auto-detects from location or searches all feeds if omitted
query (optional) - Station name to search for
route_id (optional) - Get stations on a specific route (requires feed_id)
latitude (optional) - Latitude for geographic search
longitude (optional) - Longitude for geographic search
radius (optional) - Search radius in km (default: 0.5)
Examples:
// Search for "Sol" station in Madrid
{
"feed_id": "madrid",
"query": "Sol"
}
// Find nearby stations (auto-detects feed)
{
"latitude": 40.4168,
"longitude": -3.7038,
"radius": 0.5
}
// Get all stations on Line 1
{
"feed_id": "madrid",
"route_id": "4__1___"
}
// Search all feeds
{
"query": "Central"
}
2. get_routes - Get GTFS Routes/Lines
Get information about transit routes/lines.
Parameters:
feed_id (optional) - Feed ID (required unless using query)
route_id (optional) - Specific route ID
line_number (optional) - Line short name (e.g., "1", "2", "3")
query (optional) - Search all feeds for route name
metro_only (optional) - Only return metro routes
Examples:
// Get all Madrid metro lines
{
"feed_id": "madrid",
"metro_only": true
}
// Get specific line by number
{
"feed_id": "madrid",
"line_number": "1"
}
// Search for routes globally
{
"query": "Airport"
}
3. get_schedule - Get Schedule/Timetable
Get arrival/departure times for a specific stop.
Parameters:
feed_id (required) - Feed ID
stop_id (required) - Stop ID
time (optional) - Time in HH:MM:SS format (default: current time)
date (optional) - Date in YYYYMMDD format (default: today)
limit (optional) - Max number of arrivals (default: 10)
Examples:
// Get next trains at Sol station
{
"feed_id": "madrid",
"stop_id": "par_4_12",
"limit": 5
}
// Get schedule at specific time
{
"feed_id": "madrid",
"stop_id": "par_4_12",
"time": "09:00:00",
"date": "20251007"
}
Enhanced Journey Planning Tools ✨
4. get_station_details - Get Comprehensive Station Information
Get complete details about a station including all serving lines, entrances, nearby stations, and transfer options.
Parameters:
feed_id (required) - Feed ID
stop_id (required) - Station/stop ID
Example:
{
"feed_id": "madrid",
"stop_id": "par_4_12"
}
Returns:
- Station information (name, location, accessibility)
- All serving lines with directions
- Station entrances/accesses
- Nearby stations (within 500m) with common lines
- Available transfer options
5. get_line_path - Get Complete Line Path
Get the complete ordered sequence of stations for a transit line, including all directions, travel times, and transfer options.
Parameters:
feed_id (required) - Feed ID
line_number (required) - Line/route number (e.g., "1", "2", "L6")
Example:
{
"feed_id": "madrid",
"line_number": "1"
}
Returns:
- Line information (number, name, color)
- All directions with headsigns
- Ordered station sequences
- Transfer options at each station
- Travel times between consecutive stations
6. find_connections - Find Transfer Stations
Find transfer/interchange stations between transit lines.
Parameters:
feed_id (required) - Feed ID
from_line (optional) - Starting line number
to_line (optional) - Destination line number
Examples:
// Find all transfer stations
{
"feed_id": "madrid"
}
// Find transfers from Line 1
{
"feed_id": "madrid",
"from_line": "1"
}
// Find specific connection between Line 1 and Line 4
{
"feed_id": "madrid",
"from_line": "1",
"to_line": "4"
}
Returns:
- List of transfer stations
- All lines available at each station
- Estimated transfer times
7. plan_journey - Door-to-Door Journey Planning ✨
Plan complete journeys from origin to destination combining walking and transit.
Parameters:
from_lat (required) - Origin latitude
from_lon (required) - Origin longitude
to_lat (required) - Destination latitude
to_lon (required) - Destination longitude
feed_id (optional) - Specific feed to use (auto-detects if omitted)
max_walking_distance (optional) - Maximum walking distance to stations in km (default: 1.0)
Example:
// Plan journey in Madrid
{
"from_lat": 40.4168,
"from_lon": -3.7038,
"to_lat": 40.4919,
"to_lon": -3.5932,
"feed_id": "madrid"
}
Returns:
- Complete journey with walking and transit legs
- Step-by-step directions
- Total duration and walking distance
- Transfer information
Architecture:
This tool uses a hybrid approach:
- OpenRouteService API - Provides accurate walking directions and times for first/last mile
- Local GTFS data - Routes transit connections using local database
- Fallback - Estimated times used if OpenRouteService unavailable
Setup:
Requires OpenRouteService API key in environment:
# .env file
OPENROUTESERVICE_API_KEY=your_api_key_here
Get a free API key at OpenRouteService.
Current Limitations:
- Supports direct routes or single transfer only
- Multi-transfer optimization not yet implemented
- Time-specific routing (departures/arrivals) not yet supported
Environment Configuration
Create a .env file with your API keys:
# OpenRouteService (for journey planning walking directions)
OPENROUTESERVICE_API_KEY=your_key_here
The server will automatically detect and enable journey planning if the OpenRouteService API key is present. All other tools work without any API keys.
Adding New Feeds
1. Download GTFS Data
Find and download GTFS feeds from Transit.land:
Example feeds:
mkdir -p gtfs/barcelona
cd gtfs/barcelona
# Download GTFS zip from Transit.land feed page
# Extract all .txt files here
cd ../..
See gtfs/README.md for detailed download instructions.
2. Update Configuration
Add feed configuration to feeds.config.json:
{
"feeds": [
{
"id": "barcelona",
"name": "TMB Barcelona",
"region": "Barcelona",
"country": "Spain",
"gtfsPath": "gtfs/barcelona",
"databasePath": "databases/feeds/barcelona.db",
"timezone": "Europe/Madrid",
"coverage": {
"bounds": {
"min_lat": 41.3,
"max_lat": 41.5,
"min_lon": 2.0,
"max_lon": 2.3
}
},
"metadata": {
"agency": "TMB",
"website": "https://www.tmb.cat",
"modes": ["metro", "bus"],
"language": "es"
}
}
]
}
3. Import the Feed
4. Restart the Server
The new feed will be automatically available!
Database Schema
Each feed has its own SQLite database with GTFS tables:
agency - Transit agency information
routes - Routes/lines
stops - Stops/stations
trips - Individual trips
stop_times - Arrival/departure times
calendar - Service schedules
calendar_dates - Service exceptions
shapes - Geographic paths (optional)
frequencies - Headway-based service (optional)
Multi-Feed Query Strategies
Auto-Detection
Provide lat/lon to automatically find relevant feeds:
{ "latitude": 40.4168, "longitude": -3.7038 }
Specific Feed
Target a specific feed:
{ "feed_id": "madrid", "query": "Sol" }
Global Search
Search across all feeds:
{ "query": "Central Station" }
Performance
- Indexed queries - All common queries use database indexes
- Lazy loading - Feeds only loaded when accessed
- Connection pooling - Reuses database connections
- Parent station filtering - Returns only main stations, not all entrances
Data Statistics (Madrid)
- Routes: 13 metro lines + Ramal
- Stops: 1,050 total (300+ parent stations)
- Trips: 120 unique trips
- Stop Times: 2,216 scheduled stops
- Calendar: 4 service patterns (weekday, Friday, Saturday, Sunday)
- Shapes: 57,474 geographic points
License
MIT