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:

brew install uv

Or via the official installer (macOS/Linux):

curl -LsSf https://astral.sh/uv/install.sh | sh
# then restart your shell or source the profile output by the installer

Project setup

1. Clone or download the server file/repo
2. Create the virtual environment and install dependencies with uv:

uv sync

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

1. Set up environment variable:

export DUFFEL_ACCESS_TOKEN="your_duffel_token_here"

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):

uv run python duffel_mcp.py

Configuration for Claude Desktop

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

{
  "mcpServers": {
    "duffel": {
      "command": "uv",
      "args": ["run", "python", "/path/to/duffel_mcp.py"],
      "env": {
        "DUFFEL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

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:

{
  "slices": [
    {
      "origin": "JFK",
      "destination": "LAX",
      "departure_date": "2025-12-15"
    },
    {
      "origin": "LAX",
      "destination": "JFK",
      "departure_date": "2025-12-22"
    }
  ],
  "passengers": [
    {"age": 35},
    {"age": 32},
    {"age": 8}
  ],
  "cabin_class": "economy",
  "max_connections": 1
}

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:

{
  "offer_id": "off_00009htYpSCXrwaB9DnUm0",
  "passengers": [
    {
      "id": "pas_00009hj8USM7Ncg31cBCL",
      "given_name": "John",
      "family_name": "Smith",
      "born_on": "1985-03-15",
      "email": "john.smith@example.com",
      "phone_number": "+14155551234",
      "gender": "m",
      "title": "mr"
    }
  ],
  "payments": [
    {
      "type": "balance",
      "amount": "520.00",
      "currency": "USD"
    }
  ]
}

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:

Search for round-trip flights from New York to London, departing Dec 15, returning Dec 22, 
2 adult passengers, economy class, direct flights only

1. Get offer details:

Get the latest pricing for offer off_00009htYpSCXrwaB9DnUm0

1. Create booking:

Book this offer with passengers: John Smith (john@example.com, +14155551234, DOB 1985-03-15) 
and Jane Smith (jane@example.com, +14155551235, DOB 1987-07-20). Use balance payment for $1,450.00 USD.

Finding Airports

What airports are in the London area?

What's the airport code for San Francisco International?

Best Practices

Do's

1. Use age over type - 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

# Set test token
export DUFFEL_ACCESS_TOKEN="duffel_test_xxx"

# Run server with uv
uv run python duffel_mcp.py

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