Duffel Airfare Query Engine

This service acts as a Model Context Protocol (MCP) interface to the Duffel Aviation API, facilitating sophisticated, context-aware searches for commercial flights.

Operational Framework

This component connects the conversational agent to live flight data streams.

Demonstration

See the system in action: https://github.com/user-attachments/assets/c111aa4c-9559-4d74-a2f6-60e322c273d4

Utility Rationale

Traditional static travel aggregators falter when itineraries become intricate. This platform excels by integrating the search mechanism directly into the chat environment, offering significant advantages:

• Persistent Contextual Awareness: The system retains all prior flight search parameters throughout the dialogue session, eliminating the need for users to re-specify constraints.
• Granular Date Range Analysis: Facilitates broad date scanning to pinpoint optimal fares across adjacent days without repetitive manual input.
• Advanced Routing Capability: Superior management of non-linear itineraries, including multi-stop journeys and comparative analysis of various routing combinations.
• Intuitive Interaction: Users articulate travel requirements conversationally; the system autonomously parses geographical codes, temporal constraints, and passenger counts, sidestepping cumbersome graphical user interfaces.

Consider this your dedicated digital flight concierge, capable of instant, memory-retaining cross-referencing of routes and schedules.

Core Functionality

• Query services for flights spanning multiple origin/destination pairs.
• Comprehensive support for one_way, round_trip, and multi_city trip structures.
• Extraction of comprehensive flight offer schemas.
• Utilization of fine-grained search attributes (e.g., preferred departure windows, seating class, passenger count).
• Automated resolution and management of flight segments and connections.
• Capability to search across date intervals to discover superior routing solutions (Note: This feature may increase latency).

Prerequisites for Operation

• A functional Python 3.x runtime environment.
• A valid Duffel API credential (Production or Test).

Acquiring Duffel Credentials

Although Duffel necessitates verification and financial setup for full functionality, this MCP integration strictly utilizes read-only search endpoints, ensuring no transactions are initiated.

Initial Exploration: Test Mode (Recommended)

Start by configuring the service with the provided test credential (duffel_test) to explore functionality using simulated data: 1. Navigate to Duffel's Account Creation Portal. 2. Register an account (using 'Personal Use' is acceptable for company identification). 3. Locate your test API token under the 'Developer' settings (a default token is usually present).

Transitioning to Live Credentials

To access live market data, the following steps must be completed within the Duffel dashboard: 1. Deactivate 'Test Mode' in the dashboard header. 2. Progress through mandatory verification checkpoints, which often require repeatedly toggling 'Test Mode' off to unlock the next stage: - Email verification. - Business/Company detail submission (Personal Use is viable). - Payment instrument linkage (Required by Duffel for verification, but no charges are routed through this MCP tool). - Final compliance steps. 3. Upon final confirmation, generate a 'Live Token' under Developer settings.

💡 Note on Verification: Each successful step requires re-disabling 'Test Mode' to advance the process.

⚠️ Critical Security & Usage Information: - All sensitive access credentials remain secured locally on the host machine. - This integration is strictly read-only; booking or charging capabilities are deliberately omitted. - Payment data is managed exclusively by Duffel; it is never accessed, stored, or transmitted by this application. - The duffel_test key is sufficient for initial validation of the service.

Local Installation Procedure

Installation via Smithery (Automated)

Deploy Find Flights for Claude Desktop using the Smithery utility:

npx -y @smithery/cli install @ravinahp/travel-mcp --client claude

Manual Repository Checkout

Clone the source repository:

git clone https://github.com/ravinahp/flights-mcp
cd flights-mcp

Dependency resolution is managed via pyproject.toml using the uv tool:

uv sync

Configuration as an MCP Endpoint

Integrate this service into your Claude Desktop configuration file (claude_desktop_config.json). The file paths are OS-dependent: - MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

Incorporate the following structure, substituting placeholders:

{
    "duffel-flight-explorer": {
        "command": "uv",
        "args": [
            "--directory",
            "/Users/YOUR_USERNAME/Code/flights-mcp",
            "run",
            "flights-mcp"
        ],
        "env": {
            "DUFFEL_API_KEY_LIVE": "your_duffel_live_api_key_here"
        }
    }
}

⚠️ Configuration Alert: - Ensure YOUR_USERNAME and the API key are correctly substituted. - Verify the local installation directory path is accurate.

Packaging and Distribution

To prepare the service for deployment or inspection:

# Synchronize dependencies and generate lockfile
uv sync

# Build distribution artifacts
uv build

Artifacts will reside in the dist/ folder.

Diagnostic Utility

Use the MCP Inspector for in-depth monitoring and debugging:

npx @modelcontextprotocol/inspector uv --directory /path/to/duffel-flight-explorer run flights-mcp

The Inspector offers visualization of request/response payloads, schema conformance checks, performance telemetry, and error tracing.

Exposed Operations

1. Air Segment Search

@mcp.tool()
async def search_flights(params: FlightSearch) -> str:
    """Executes a broad search across available air segments."""

Supports single leg, bidirectional, and multi-leg travel modes. Required parameters: - type: ('one_way', 'round_trip', 'multi_city') - origin: IATA departure code - destination: IATA arrival code - departure_date: Format YYYY-MM-DD Optional constraints: - return_date: Required for round trips - adults: Passenger count - cabin_class: Seating preference - departure_time: Time window specification - arrival_time: Time window specification - max_connections: Limit on layovers allowed

2. Offer Data Retrieval

@mcp.tool()
async def get_offer_details(params: OfferDetails) -> str:
    """Fetches exhaustive specifics for a given flight offer identifier."""

Requires a unique Offer ID to return comprehensive pricing and routing structure.

3. Multi-Segment Search Specialization

@mcp.tool(name="search_multi_city")
async def search_multi_city(params: MultiCityRequest) -> str:
    """Dedicated function for querying complex, sequential travel plans."""

Parameters: - segments: Ordered list defining each leg of the journey. - adults, cabin_class, max_connections: As defined above.

Illustrative Interaction Scenarios

Users can frame requests naturally: - "Locate a single outbound flight from SFO to JFK on 2025-01-07 for two passengers traveling Business." - "Compare return flights between LAX and LHR, leaving mid-day on Jan 8th and returning on Jan 15th." - "Develop an itinerary starting in NYC, flying to Paris on Jan 7, then Rome on Jan 10, concluding back in NYC on Jan 15." - "Determine the most economical SFO-LAX route between 7th and 15th of January for two economy travelers." - Explore flexible date options, though multi-city date range searches are best avoided for performance.

Data Output Schema

Results are furnished as structured JSON, detailing: - Offer pricing components. - Segment-specific route data (slices). - Operating carrier identification. - Connection path specifics.

Robust Error Management

The service implements comprehensive failure interception for: - Duffel API communication errors. - Invalid airport or date formatting. - Missing API credential authorization. - Network latency failures. - Parameter validation failures.

Licensing

MIT License. Refer to the LICENSE file.

Operational Constraints

• Standard searches are capped at returning the top 50 relevant offers.
• Multi-city queries are limited to the top 10 results.
• Supplier response timeouts are dynamically set between 15 to 30 seconds based on query complexity.

Cabin Class Enumeration

Available service classes: - economy - premium_economy - business - first

Example Configuration Snippet (Business Class Request):

{
  "params": {
    "type": "one_way",
    "adults": 1,
    "origin": "SFO",
    "destination": "LAX",
    "departure_date": "2025-01-12",
    "cabin_class": "business" 
  }
}