Duffel MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact with the Duffel API for searching and booking flights, accommodations, and managing travel bookings.

Features

✈️ Flight Operations

• Search Flights - Find available flights with pricing, schedules, and airline information

• Get Offer Details - Retrieve up-to-date pricing and availability for specific offers

• Create Orders - Book flights with passenger details and payment

• Manage Orders - View and manage existing bookings

🌍 Supporting Resources

• Search Airports - Find airports by name, city, or IATA code

• List Airports - Browse airports with country filtering

🎯 Key Capabilities

• 300+ Airlines - Access to major airlines via NDC, GDS, and LCC

• Real-time Data - Live pricing, availability, and seat selection

• Flexible Search - One-way, round-trip, multi-city support

• Smart Responses - JSON or Markdown formatted output

• Error Handling - Clear, actionable error messages

Installation

Prerequisites

• Python 3.12 or higher

• Duffel API account (sign up here)

• Duffel API access token

• uv (fast Python package manager)

Install uv

On macOS with Homebrew:

Or via the official installer (macOS/Linux):

Project setup

1. Clone or download the server file/repo

2. Create the virtual environment and install dependencies with uv:

This uses pyproject.toml to create .venv and install exact versions.

3. Set up environment variable:

Get your token from the Duffel Dashboard:

• Navigate to: More → Developers → Access Tokens

• Create a test token for testing (free, unlimited balance)

• Create a live token for production bookings

Usage

Running the Server

Run with uv (uses the synced virtualenv automatically):

Configuration for Claude Desktop

Add to your Claude Desktop config file (claude_desktop_config.json):

Configuration for Other MCP Clients

For other MCP clients, follow their specific configuration format, ensuring:

• The server is launched with Python 3.12+

• DUFFEL_ACCESS_TOKEN environment variable is set

• Server communicates via stdio

Available Tools

1. duffel_search_flights

Search for available flights based on journey requirements.

Parameters:

• slices - Journey legs (origin, destination, date)

• passengers - List of travelers (use age for best accuracy)

• cabin_class - Optional: economy, premium_economy, business, first

• max_connections - Optional: limit stops (0 = direct flights)

• response_format - json or markdown

Example:

2. duffel_get_offer

Retrieve current pricing and details for a specific offer.

Parameters:

• offer_id - Offer ID from search results

• response_format - json or markdown

Important: Always call this before booking to ensure offer is still valid and get current pricing.

3. duffel_create_order

Create a flight booking with passenger details and payment.

Parameters:

• offer_id - Offer ID to book

• passengers - Complete passenger details (name, DOB, contact)

• payments - Payment information

• response_format - json or markdown

⚠️ Warning: This creates real bookings! Use test tokens for development.

Example:

4. duffel_get_order

Retrieve details for an existing order.

Parameters:

• order_id - Order ID from booking

• response_format - json or markdown

5. duffel_search_airports

Search for airports by name, city, or code.

Parameters:

• query - Search term (e.g., "London", "Heathrow", "LHR")

• limit - Max results (1-100, default: 20)

• response_format - json or markdown

6. duffel_list_airports

List airports with optional country filter.

Parameters:

• country_code - Optional: ISO country code (e.g., "US", "GB")

• limit - Results per page (1-200, default: 50)

• response_format - json or markdown

Typical Workflows

Booking a Flight

1. Search for flights:

2. Get offer details:

3. Create booking:

Finding Airports

Best Practices

✅ Do's

1. Use - Provides better accuracy across airlines

2. Check offer expiry - Offers expire in 15-30 minutes

3. Verify before booking - Always retrieve offer for current price

4. Test mode first - Use test tokens during development

5. Handle async responses - Some bookings return 200/202 with webhook notifications

❌ Don'ts

1. Don't retry failed bookings - If order creation fails, don't retry the same request

2. Don't cache offers - Always fetch fresh data before booking

3. Don't ignore validation errors - They guide toward correct usage

4. Don't use expired offers - Check expires_at timestamp

Error Handling

The server provides clear, actionable error messages:

• offer_expired - Perform new search

• offer_no_longer_available - Select different offer

• price_changed - Retrieve offer again for updated price

• validation_error - Check parameter formats and requirements

• payment_declined - Verify payment details

Testing

Test Mode

Duffel provides unlimited test balance:

1. Create a test access token in dashboard

2. Use "type": "balance" for payments

3. Search and book without actual charges

4. Use test airline: "Duffel Airways"

Manual Testing

Then interact through your MCP client to test various workflows.

API Reference

For complete Duffel API documentation:

• Getting Started Guide

• API Reference

• Response Handling

Troubleshooting

"DUFFEL_ACCESS_TOKEN environment variable not set"

Set the environment variable with your Duffel API token.

"offer_expired" errors

Offers have short expiry times (15-30 min). Perform a new search.

"validation_error" on booking

• Check passenger names match government ID exactly

• Verify date format is YYYY-MM-DD

• Ensure payment amount matches offer total

• Confirm all required fields are provided

"No flights found"

• Verify airport codes are valid IATA codes (use duffel_search_airports)

• Check dates are in future

• Try broader search criteria (more connections, different cabin class)

Webhooks not received

• Configure webhook URLs in Duffel Dashboard

• Check your email for booking confirmations

• Use duffel_get_order to manually check order status

License

This MCP server is provided as-is for integration with Duffel API. See Duffel's terms of service for API usage terms.

Support

• Duffel Documentation: https://duffel.com/docs

• Duffel Support: https://support.duffel.com

• MCP Documentation: https://modelcontextprotocol.io

Contributing

Contributions welcome! Potential enhancements:

• Stays API integration (hotel bookings)

• Order modifications and cancellations

• Seat selection tools

• Baggage management

• Loyalty program integration

• Advanced filtering options

Version History

• v0.1.0 - Initial release

  • Flight search and booking

  • Order management

  • Airport search

  • Markdown and JSON output formats