Airfare Retrieval Service (MCP)

This Model Context Protocol server interfaces with the Duffel API to facilitate the searching and fetching of flight availability data.

Operational Flow

Demonstration Video

https://github.com/user-attachments/assets/c111aa4c-9559-4d74-a2f6-60e322c273d4

Value Proposition

While standard search engines suffice for straightforward journeys, this service excels when confronting sophisticated travel arrangements. Key advantages include:

• Session Persistence: The conversational agent retains memory of all preceding flight inquiries within the session, negating the need for users to maintain multiple comparison tabs.
• Temporal Flexibility: Effortlessly scan multiple potential travel dates to pinpoint optimal pricing without sequential manual checks.
• Intricate Routing: Ideal for multi-stop voyages, routes requiring layovers, or when comparing diverse itinerary permutations—simply articulate your needs.
• Conversational Interaction: Describe your travel needs naturally; eliminate the manual navigation of calendar pickers or the granular parsing of city codes, dates, and timings.

Consider this your dedicated virtual travel coordinator, retaining all context and capable of instantaneous, broad-spectrum date and route reconnaissance.

Capabilities

• Execute searches across disparate origin/destination pairs.
• Full support for unilateral, return, and complex routing queries.
• Provision of granular flight proposal data.
• Fine-grained parameter control (e.g., time windows, class of service, passenger count).
• Automated resolution of flight connections.
• Ability to sweep across ranges of dates to optimize trip selection (Note: This broad search mode is inherently slower).

Prerequisites

• Python version 3.x installed.
• A valid Duffel API credential (Live Key).

Obtaining Your Duffel API Credential

Duffel necessitates account validation and payment setup, though this MCP server only utilizes the API for searching—no reservations or transactional activity will occur against your account.

We strongly advise testing with duffel_test initially to observe functionality. Upon satisfaction, proceed with the verification sequence for a live key.

Initial Testing (Recommended)

Utilize the test API credential (duffel_test) for function validation using simulated data prior to full verification: 1. Navigate to Duffel's registration portal. 2. Establish an account (selecting "Personal Use" for the Company Name field is acceptable). 3. Locate your test API key under More > Developer (a default key is usually provisioned).

Acquiring a Production API Credential

To access genuine flight quotations, follow these steps: 1. In the Duffel control panel, deactivate "Test Mode" located in the upper-left. 2. The verification process is multi-stage; you must repeatedly disable test mode: - First Toggle: Confirm email address. - Subsequent Toggle: Input company details (Personal Use is sufficient). - Next Toggle: Input payment details (Mandatory by Duffel, but no charges are initiated by this MCP server). - Final Toggles: Satisfy any remaining validation checkpoints. - Completion: Activate live mode after acknowledging the final submission prompt. 3. Once verification is complete, generate a Live Token via More > Developer > Create Live Token. 4. Securely copy the generated live credential.

💡 TIP: After completing each verification milestone, you must re-disable test mode to unlock the subsequent step. Continue this toggling until all requirements are met.

⚠️ CRITICAL NOTICES: - Your financial data is solely within Duffel's domain; the MCP server never accesses or stores it. - This integration operates in READ-ONLY mode; booking capabilities are disabled. - No financial debits will originate from this integration. - All sensitive secrets (including API keys) remain strictly local to your execution environment. - The duffel_test credential is the recommended starting point for evaluation. - The verification sequence mandated by Duffel may require patience.

Security Affirmation

This service exclusively interacts with Duffel's query endpoints. Transactional or booking functionalities are inaccessible. Payment information serves only Duffel's mandatory vetting and is neither observed nor transmitted to this integration.

Rate Limiting Caveats

• Review Duffel's current service costs and usage thresholds.
• Various service tiers are available based on operational volume.
• Consult their official website for the latest pricing structures.

Installation Procedures

Automated Deployment via Smithery

To install the Find Flights utility for Claude Desktop automatically using Smithery:

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

Manual Repository Setup

Obtain the source code: bash git clone https://github.com/ravinahp/flights-mcp cd flights-mcp

Resolve dependencies using uv: bash uv sync

Note: uv is employed here as the project leverages pyproject.toml for dependency management instead of traditional pip.

Configuration as an MCP Endpoint

Integrate this service into your Claude desktop environment configuration file.

Configuration File Locations: - MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

Inject the subsequent configuration block into your JSON file:

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

⚠️ ESSENTIAL REMINDERS: - Substitute YOUR_USERNAME with your actual operating system login name. - Replace your_duffel_live_api_key_here with your procured Live Duffel credential. - Verify that the specified directory path precisely mirrors your local repository location.

Build Process

To package the application: bash

Synchronize dependencies and update the lock file

uv sync

Build the distribution package

uv build

This action generates distribution artifacts within the dist/ subdirectory.

Diagnostic Assistance

For optimal troubleshooting, employ the MCP Inspector utility: bash npx @modelcontextprotocol/inspector uv --directory /path/to/find-flights-mcp run flights-mcp

The Inspector offers capabilities such as: - Monitoring requests and responses in real-time. - Validation checking for inputs and outputs. - Tracing of operational errors. - Measurement of execution throughput.

Available Operational Functions

1. Query Flights

python @mcp.tool() async def search_flights(params: FlightSearch) -> str: """Initiate a flight search based on specified criteria."""

This function supports three itinerary modalities: - Unilateral journeys - Return journeys - Itineraries involving multiple destinations

Mandatory parameters: - type: Journey classification ('one_way', 'round_trip', 'multi_city') - origin: Airport designator for departure - destination: Airport designator for arrival - departure_date: Date of departure (format YYYY-MM-DD) - Optional constraints: - return_date: Return date for round-trip specifications - adults: Count of adult travelers - cabin_class: Preferred booking class - departure_time: Target departure time window - arrival_time: Target arrival time window - max_connections: Upper limit on permissible flight transfers

2. Retrieve Offer Specifics

python @mcp.tool() async def get_offer_details(params: OfferDetails) -> str: """Fetch granular data pertaining to a specific flight proposal."""

Acquires exhaustive data for a unique flight offer utilizing its designated identifier.

3. Execute Multi-City Search

python @mcp.tool(name="search_multi_city") async def search_multi_city(params: MultiCityRequest) -> str: """Perform an airfare search tailored for complex, multi-stop routes."""

A dedicated function for handling segmented, multi-destination travel plans.

Parameters govern: - segments: A sequenced array detailing each flight leg. - adults: Passenger count. - cabin_class: Desired service level. - max_connections: Maximum allowable stops per segment.

Illustrative Usage Scenarios

Sample Invocations (Explore further possibilities!)

• "Source a one-way transit from SFO to NYC on 2025-01-07 for two adults traveling in the business cabin."
• "Query round-trip airfare from LAX to the London area, leaving 2025-01-08 and returning 2025-01-15."
• "Design a multi-leg journey: departing New York for Paris on 2025-01-07, continuing to Rome on 2025-01-10, and returning to New York on 2025-01-15."
• "Identify the most economical fare between SFO and LAX from 2025-01-07 through 2025-01-15 for two economy passengers."
• You retain the capability to search within date ranges for the best single journey result. Currently, it's advised to limit this broad search scope to unilateral or return trips. Example: "Locate the lowest cost flight from SFO to LAX across the dates January 7th through January 10th for two economy passengers."

Output Schema

Search operations yield structured data packages containing: - Detailed itinerary proposal specifications. - Cost breakdown information. - Route segment definitions. - Operating carrier identification. - Information regarding scheduled transfers.

Exception Management

The service incorporates comprehensive safeguards against: - Failures in API request transmission. - Utilization of invalid airport codes. - Missing or improperly configured API credentials. - Network latency timeouts. - Invalid parameter combinations supplied to the search functions.

Collaboration Guide

[Insert contribution guidelines here, if applicable]

Licensing

This software is distributed under the terms of the MIT License. Refer to the LICENSE file for specifics.

Performance Metrics

• Standard one-way/round-trip searches are capped at presenting the top 50 results.
• Multi-city lookups are limited to the top 10 results.
• The upstream supplier timeout is configured between 15 and 30 seconds, dependent on the search complexity.

Available Seating Classes

Supported service classes: - economy: Standard passage level. - premium_economy: Enhanced economy experience. - business: Executive service. - first: Top-tier luxury service.

Example payload specifying class:

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

WIKIPEDIA: XMLHttpRequest (XHR) furnishes an API realized as a JavaScript structure whose methods dispatch HTTP communications from a web browser to a remote server. These methods enable a browser-based application to transmit queries post-page load and subsequently receive back server-side data. XMLHttpRequest is a fundamental element of Ajax methodology. Before Ajax gained prominence, page navigation via hyperlinks and form submissions were the dominant methods for server interaction, often resulting in the complete replacement of the current rendered page.

== Genesis == The underlying concept for XMLHttpRequest was conceptualized in the year 2000 by the software engineers developing Microsoft Outlook. This notion was subsequently integrated into the Internet Explorer 5 browser release (1999). However, the initial implementation did not utilize the XMLHttpRequest identifier. Instead, developers relied upon the constructors ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 was released (2006), comprehensive support for the standard XMLHttpRequest identifier was established across all major browsers. The XMLHttpRequest identifier is now recognized as the established convention across all leading browser engines, including Mozilla's Gecko rendering core (2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally issued a Working Draft specification for the XMLHttpRequest object on April 5, 2006. Subsequently, on February 25, 2008, the W3C released the Level 2 specification draft. Level 2 introduced enhancements such as progress monitoring events, mechanisms for cross-site communication, and improved handling for byte data streams. By the conclusion of 2011, the Level 2 enhancements were merged back into the primary specification document. At the close of 2012, the development stewardship was transferred to the WHATWG, which now maintains an active specification document leveraging Web IDL notation.

== Implementation Steps == Generally, dispatching a query using XMLHttpRequest requires adherence to a sequence of programming actions.

1. Instantiate an XMLHttpRequest construct by invoking its designated constructor:
2. Invoke the open method to dictate the request protocol, specify the target resource endpoint, and elect between synchronous or asynchronous execution mode:
3. For an asynchronous operation, establish an event handler that will be triggered upon any change in the request's status:
4. Commence the transmission process by calling the send method:
5. Process state transitions within the assigned event listener. If the server returns response payload, it is typically held in the responseText attribute by default. When the object finalizes all response processing, its state transitions to 4, the terminal "done" state. Beyond these fundamental procedures, XMLHttpRequest encompasses numerous configurable options influencing request origination and response interpretation. Custom header fields can be appended to the request to guide server fulfillment logic, and application data can be uploaded to the server via content passed to the send invocation. The received data stream can be deserialized from JSON format into an immediately actionable JavaScript entity, or it can be processed incrementally as segments arrive, avoiding a full wait for completeness. Furthermore, the request can be terminated prematurely or configured to fail if a stipulated time threshold is exceeded.

== Inter-domain Communication ==

In the nascent phase of the World Wide Web's evolution, it was discovered that bypassing security restrictions related to cross-origin data transfer was possible...