Find Flights (Duffel) MCP server

This MCP server lets you search for and retrieve flight information using the Duffel API. It works like having a travel agent in your chat that remembers your previous searches and helps you find the best flights for complex travel plans.

Installation

Option 1: Install via Smithery

For an automatic installation with Claude Desktop:

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

Option 2: Manual Installation

Clone the repository and install dependencies:

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

Setting Up Your Duffel API Key

Try Test Mode First (Recommended)

Start with a test API key to try the functionality with simulated data:

1. Use the pre-provided test key: duffel_test

Getting a Live API Key

For real flight data:

1. Create an account at Duffel's registration page
2. Toggle "Test Mode" off in the dashboard
3. Complete the verification process (requires multiple toggles):
   • Verify email
   • Complete company information
   • Add payment information
   • Complete any remaining steps
4. Go to More > Developer > Create Live Token
5. Copy your live API key

Important Security Notes:

• Your payment info is handled by Duffel only
• This MCP server is read-only (searches only, no bookings)
• No charges will be made through this integration
• API keys remain local to your machine

Configure as MCP Server

Modify your Claude desktop configuration file:

File locations:

• MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Add this configuration:

{
    "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"
        }
    }
}

Important:

• Replace YOUR_USERNAME with your actual username
• Replace your_duffel_live_api_key_here with your Duffel API key
• Ensure the directory path matches your installation

Using the Flight Search Tool

Search Flights

This tool supports one-way, round-trip, and multi-city flights with these parameters:

• type: Flight type ('one_way', 'round_trip', 'multi_city')
• origin: Origin airport code
• destination: Destination airport code
• departure_date: Departure date (YYYY-MM-DD)
• Optional parameters:
  • return_date: Return date for round-trips
  • adults: Number of adult passengers
  • cabin_class: Preferred cabin class ('economy', 'premium_economy', 'business', 'first')
  • departure_time: Specific departure time range
  • arrival_time: Specific arrival time range
  • max_connections: Maximum number of connections

Get Offer Details

Retrieves comprehensive details for a specific flight offer using its unique ID.

Search Multi-City Flights

Specialized tool for complex multi-city flight itineraries with parameters:

• segments: List of flight segments
• adults: Number of adult passengers
• cabin_class: Preferred cabin class
• max_connections: Maximum number of connections

Example Queries

Try asking Claude:

• "Find a one-way flight from SFO to NYC on Jan 7 for 2 adults in business class"
• "Search for a round-trip flight from LAX to London, departing Jan 8 and returning Jan 15"
• "Plan a multi-city trip from New York to Paris on Jan 7, then to Rome on Jan 10, and back to New York on Jan 15"
• "What is the cheapest flight from SFO to LAX from Jan 7 to Jan 15 for 2 adults in economy class?"

For finding the best deals, you can search across multiple days (works best with one-way or round-trip flights):

• "Find the cheapest flight from SFO to LAX from Jan 7 to Jan 10 for 2 adults in economy class"

Debugging

For troubleshooting, use the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/find-flights-mcp run flights-mcp

This provides real-time monitoring, validation, error tracking, and performance metrics.

Performance Notes

• Searches are limited to 50 offers for one-way/round-trip flights
• Multi-city searches are limited to 10 offers
• Supplier timeout is 15-30 seconds depending on search type

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "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"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "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"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect