# Travel Amadeus MCP Server
A Model Context Protocol (MCP) server that provides access to all Amadeus Travel APIs. This allows AI assistants to search flights, book hotels, find activities, and access comprehensive travel data.
## Features
### Flight APIs
- **Flight Search** - Search for flight offers with flexible dates and routes
- **Flight Booking** - Create, retrieve, and cancel flight orders
- **Flight Inspiration** - Find cheapest destinations from origin
- **Flight Availability** - Advanced availability search
- **Seat Maps** - View available seats on flights
- **Branded Fares** - Get upsell options with additional services
- **Flight Status** - Real-time flight tracking
### Hotel APIs
- **Hotel Search** - Find hotel offers by city or coordinates
- **Hotel Booking** - Book hotel rooms
- **Hotel Listings** - List hotels by city or location
- **Hotel Sentiments** - Get review sentiment analysis
### Activities & Points of Interest
- **Activities Search** - Find tours and activities by location
- **Points of Interest** - Discover tourist attractions
- **Activity Details** - Get detailed activity information
### Transfer Services
- **Transfer Search** - Find private transfer options
- **Transfer Booking** - Book ground transportation
- **Transfer Cancellation** - Cancel transfer bookings
### Travel Intelligence
- **Travel Analytics** - Most booked/traveled destinations, busiest periods
- **Price Analysis** - Flight price metrics and quartile distributions
- **Predictions** - Flight delay, trip purpose, on-time performance
- **Location Scores** - Safety and tourism ratings
### Reference Data
- **Location Search** - Find airports and cities (autocomplete)
- **Airline Lookup** - Get airline information
- **Check-in Links** - Airline check-in URLs
- **Route Information** - Airport and airline routes
## Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd travel-amadeus-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Get your Amadeus API credentials:
- Sign up at [Amadeus for Developers](https://developers.amadeus.com/)
- Create a new app to get your API Key (Client ID) and API Secret (Client Secret)
4. Configure environment variables:
```bash
cp .env.example .env
# Edit .env and add your credentials
```
5. Build the project:
```bash
npm run build
```
## Configuration
### Environment Variables
Create a `.env` file with the following:
```env
AMADEUS_CLIENT_ID=your_client_id_here
AMADEUS_CLIENT_SECRET=your_client_secret_here
AMADEUS_HOSTNAME=production # or "test" for testing
```
### Claude Desktop Configuration
Add to your Claude Desktop config file:
**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"amadeus": {
"command": "node",
"args": ["/absolute/path/to/travel-amadeus-mcp/dist/index.js"],
"env": {
"AMADEUS_CLIENT_ID": "your_client_id",
"AMADEUS_CLIENT_SECRET": "your_client_secret",
"AMADEUS_HOSTNAME": "production"
}
}
}
}
```
## Usage
Once configured, the MCP server provides 50+ tools to Claude. Here are some example prompts:
### Flight Search
```
Find me flights from New York to London departing on 2025-12-15
```
### Hotel Search
```
Show me hotels in Paris for check-in on 2025-12-20 and check-out on 2025-12-23
```
### Activities
```
What are the top tourist attractions near the Eiffel Tower?
```
### Travel Insights
```
What are the most popular destinations from San Francisco this month?
```
### Flight Status
```
What's the status of flight AA100 on 2025-11-15?
```
## Available Tools
The server provides 50+ MCP tools organized by category:
### Flight Tools (12)
- `flight_offers_search` - Search flight offers
- `flight_offers_pricing` - Confirm pricing
- `flight_create_order` - Book flights
- `flight_order_get` - Get booking details
- `flight_order_delete` - Cancel bookings
- `flight_inspiration_search` - Find cheap destinations
- `flight_cheapest_date_search` - Find cheapest dates
- `flight_availability_search` - Advanced search
- `seatmap_display` - View seat maps
- `branded_fares_upsell` - Get fare upgrades
- `flight_choice_prediction` - Predict preferences
- `flight_status` - Real-time status
### Hotel Tools (6)
- `hotel_offers_search` - Search hotels
- `hotel_offer_search` - Get offer details
- `hotel_booking` - Book hotels
- `hotel_list_by_city` - List hotels by city
- `hotel_list_by_geocode` - List hotels by location
- `hotel_sentiments` - Review analysis
### Activity Tools (6)
- `points_of_interest_search` - Find POIs
- `points_of_interest_by_square` - POIs in area
- `point_of_interest_details` - POI details
- `activities_search` - Find activities
- `activities_by_square` - Activities in area
- `activity_details` - Activity details
### Transfer Tools (3)
- `transfer_search` - Search transfers
- `transfer_booking` - Book transfers
- `transfer_cancellation` - Cancel transfers
### Reference Data Tools (7)
- `location_search` - Search locations
- `airport_city_search` - Find airports/cities
- `nearest_airport` - Find nearest airport
- `airline_lookup` - Airline information
- `checkin_links` - Check-in URLs
- `airport_routes` - Airport routes
- `airline_routes` - Airline routes
### Analytics Tools (4)
- `most_booked_destinations` - Popular destinations
- `most_traveled_destinations` - Travel trends
- `busiest_travel_period` - Peak periods
- `location_score` - Location ratings
### Prediction Tools (4)
- `flight_delay_prediction` - Delay likelihood
- `trip_purpose_prediction` - Business vs leisure
- `airport_on_time_performance` - On-time stats
- `flight_price_analysis` - Price metrics
## Development
### Build
```bash
npm run build
```
### Watch Mode
```bash
npm run watch
```
### Run Directly
```bash
npm run dev
```
### Testing
The project includes comprehensive tests for all 50+ API endpoints:
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage report
npm run test:coverage
```
See [TEST_GUIDE.md](TEST_GUIDE.md) for detailed testing documentation.
**Test Coverage:**
- ✅ 12 Flight API endpoints
- ✅ 6 Hotel API endpoints
- ✅ 6 Activity & POI endpoints
- ✅ 3 Transfer endpoints
- ✅ 7 Reference Data endpoints
- ✅ 8 Analytics & Prediction endpoints
- ✅ Integration tests for complete booking flows
## API Documentation
For detailed API documentation, visit:
- [Amadeus Self-Service APIs](https://developers.amadeus.com/self-service)
- [API Reference](https://developers.amadeus.com/self-service/apis-docs)
## Test vs Production
Amadeus provides two environments:
- **Test Environment**: Use test credentials for development with sample data
- **Production Environment**: Use production credentials for real bookings (charges apply)
Set `AMADEUS_HOSTNAME=test` for testing or `AMADEUS_HOSTNAME=production` for live data.
## Limitations
- Some APIs require production credentials
- Booking APIs may incur charges
- Rate limits apply based on your Amadeus account tier
- Some endpoints require specific data formats (see Amadeus documentation)
## Security Notes
- Never commit your `.env` file or credentials
- Use environment variables for sensitive data
- For production use, implement proper credential management
- Review Amadeus terms of service and API usage policies
## License
MIT
## Support
- [Amadeus Developer Portal](https://developers.amadeus.com/)
- [Amadeus Support](https://developers.amadeus.com/support)
- [MCP Documentation](https://modelcontextprotocol.io/)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
