How do I use Find Flights MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Find Flights MCP Server find flights from New York to London next week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

en es ja ko zh

Find Flights MCP Server

by ravinahp

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Find Flights MCP Server

MCP server for searching and retrieving flight information using Duffel API.

How it Works

Flight

Related MCP server: Flight + Stay Search MCP

Video Demo

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

Why This is Helpful

While tools like Google Flights work great for simple trips, this tool shines when dealing with complex travel plans. Here's why:

Contextual Memory: Claude remembers all your previous flight searches in the chat, so you don't need to keep multiple tabs open to compare prices
Flexible Date Search: Easily search across multiple days to find the best prices without manually checking each date
Complex Itineraries: Perfect for multi-city trips, one-stop flights, or when you need to compare different route options you can just ask!
Natural Conversation: Just describe what you're looking for - no more clicking through calendar interfaces or juggling search parameters down to parsing city names, dates, and times.

Think of it as having a travel agent in your chat who remembers everything you've discussed and can instantly search across dates and routes.

Features

Search for flights between multiple destinations
Support for one-way, round-trip, and multi-city flight queries
Detailed flight offer information
Flexible search parameters (departure times, cabin class, number of passengers)
Automatic handling of flight connections
Search for flights within multiple days to find the best flight for your trip (slower)

Prerequisites

Python 3.x
Duffel API Live Key

Getting Your Duffel API Key

Duffel requires account verification and payment information setup, but this MCP server only uses the API for searching flights - no actual bookings or charges will be made to your account.

Try using duffel_test first to see the power of this tool. If you end up liking it, you can go through the verification process below to use the live key.

Test Mode First (Recommended)

You can start with a test API key (duffel_test) to try out the functionality with simulated data before going through the full verification process:

Visit Duffel's registration page
Create an account (you can select "Personal Use" for Company Name)
Navigate to More > Developer to find your test API key (one is already provided)

Getting a Live API Key

To access real flight data, follow these steps:

In the Duffel dashboard, toggle "Test Mode" off in the top left corner
The verification process requires multiple steps - you'll need to toggle test mode off repeatedly:
- First toggle: Verify your email address
- Toggle again: Complete company information (Personal Use is fine)
- Toggle again: Add payment information (required by Duffel but NO CHARGES will be made by this MCP server)
- Toggle again: Complete any remaining verification steps
- Final toggle: Access live mode after clicking "Agree and Submit"
Once fully verified, go to More > Developer > Create Live Token
Copy your live API key

💡 TIP: Each time you complete a verification step, you'll need to toggle test mode off again to proceed to the next step. Keep toggling until you've completed all requirements.

⚠️ IMPORTANT NOTES:

Your payment information is handled directly by Duffel and is not accessed or stored by the MCP server
This MCP server is READ-ONLY - it can only search for flights, not book them
No charges will be made to your payment method through this integration
All sensitive information (including API keys) stays local to your machine
You can start with the test API key (duffel_test) to evaluate the functionality
The verification process may take some time - this is a standard Duffel requirement

Security Note

This MCP server only uses Duffel's search endpoints and cannot make bookings or charges. Your payment information is solely for Duffel's verification process and is never accessed by or shared with the MCP server.

Note on API Usage Limits

Check Duffel's current pricing and usage limits
Different tiers available based on your requirements
Recommended to review current pricing on their website

Installation

Installing via Smithery

To install Find Flights for Claude Desktop automatically via Smithery:

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

Manual Installation

Clone the repository:

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

Install dependencies using uv:

uv sync

Note: We use uv instead of pip since the project uses pyproject.toml for dependency management.

Configure as MCP Server

To add this tool as an MCP server, modify your Claude desktop configuration file.

Configuration file locations:

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

Add the following configuration to 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"
        }
    }
}

⚠️ IMPORTANT:

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

Deployment

Building

Prepare the package:

# Sync dependencies and update lockfile
uv sync

# Build package
uv build

This will create distributions in the dist/ directory.

Debugging

For the best debugging experience, use the MCP Inspector:

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

The Inspector provides:

Real-time request/response monitoring
Input/output validation
Error tracking
Performance metrics

Available Tools

1. Search Flights

@mcp.tool()
async def search_flights(params: FlightSearch) -> str:
    """Search for flights based on parameters."""

Supports three flight types:

One-way flights
Round-trip flights
Multi-city flights

Parameters include:

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
- departure_time: Specific departure time range
- arrival_time: Specific arrival time range
- max_connections: Maximum number of connections

2. Get Offer Details

@mcp.tool()
async def get_offer_details(params: OfferDetails) -> str:
    """Get detailed information about a specific flight offer."""

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

3. Search Multi-City Flights

@mcp.tool(name="search_multi_city")
async def search_multi_city(params: MultiCityRequest) -> str:
    """Search for multi-city flights."""

Specialized tool for complex multi-city flight itineraries.

Parameters include:

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

Use Cases

Some Example (But try it out yourself!)

You can use these tools to find flights with various complexities:

"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?"
You can even search for flights within multiple days to find the best flight for your trip. Right now, the reccomendation is to only search for one-way or round-trip flights this way. Example: "Find the cheapest flight from SFO to LAX from Jan 7 to Jan 10 for 2 adults in economy class"

Response Format

The tools return JSON-formatted responses with:

Flight offer details
Pricing information
Slice (route) details
Carrier information
Connection details

Error Handling

The service includes robust error handling for:

API request failures
Invalid airport codes
Missing or invalid API keys
Network timeouts
Invalid search parameters

Contributing

[Add guidelines for contribution, if applicable]

License

This project is licensed under the MIT License - see the LICENSE file for details.

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 set to 15-30 seconds depending on the search type

Cabin Classes

Available cabin classes:

economy: Standard economy class
premium_economy: Premium economy class
business: Business class
first: First class

Example request with cabin class:

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

Available Tools

3 tools

get_offer_detailsB

Get detailed information about a specific flight offer.

ParametersJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states it's a read operation ('Get'), implying it's non-destructive, but doesn't disclose behavioral traits like authentication requirements, rate limits, error handling, or what 'detailed information' entails beyond the input schema. This leaves significant gaps for an agent to understand how to use it effectively.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which likely defines the return structure), the description doesn't need to explain return values. However, with no annotations, 0% schema description coverage, and one parameter, the description is minimal. It covers the basic purpose but lacks usage guidelines and behavioral details, making it incomplete for optimal agent use despite the output schema's support.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions 'a specific flight offer', which aligns with the 'offer_id' parameter in the input schema. However, schema description coverage is 0%, so the schema provides no parameter descriptions. The description adds minimal semantics by implying the parameter identifies an offer, but doesn't explain format, source, or constraints, offering only basic compensation for the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'detailed information about a specific flight offer', making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'search_flights' or 'search_multi_city', which appear to be search operations rather than detail retrieval for a specific offer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing an offer ID from a previous search, or clarify that it's for retrieving details of a single, pre-identified offer rather than searching for new ones.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_flightsD

Search for flights based on parameters.

ParametersJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1.9/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure but provides none. It doesn't indicate whether this is a read-only operation, whether it requires authentication, what rate limits might apply, what format results are returned in, or any other behavioral characteristics. For a search tool that likely interacts with external APIs, this lack of transparency is a significant gap that leaves the agent guessing about important operational aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is maximally concise at just 6 words. While this conciseness comes at the expense of completeness, every word earns its place - 'Search' indicates the action, 'for flights' specifies the resource, and 'based on parameters' acknowledges the input requirements. There's no wasted verbiage or redundant phrasing, making it efficiently front-loaded despite its brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of flight search (11 parameters with nested objects, multiple flight types, and sibling tools), the description is woefully incomplete. While the presence of an output schema means the description doesn't need to explain return values, it fails to provide context about the tool's scope, limitations, or relationship to other tools. With no annotations and minimal description, the agent lacks crucial information needed to use this tool effectively in context with 'search_multi_city' and 'get_offer_details'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description states 'based on parameters' but provides zero information about what those parameters are or their semantics. With schema description coverage at 0% (the schema has descriptions but they're not counted in coverage), the description fails to compensate by explaining any of the 11 parameters documented in the schema. The agent must rely entirely on the schema to understand parameters like 'type', 'origin', 'destination', 'departure_date', etc., with no high-level guidance from the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Search for flights based on parameters' is tautological - it essentially restates the tool name 'search_flights' with minimal elaboration. While it indicates the general action (search) and resource (flights), it lacks specificity about what kind of search this performs or how it differs from sibling tools like 'search_multi_city'. The description doesn't provide meaningful differentiation from what the name already conveys.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides absolutely no guidance about when to use this tool versus alternatives. With sibling tools like 'search_multi_city' and 'get_offer_details' available, the agent receives no indication whether this is the primary search tool, whether it's for simple searches while 'search_multi_city' handles complex itineraries, or any prerequisites or constraints. The description offers zero contextual usage information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_multi_cityC

Search for multi-city flights.

ParametersJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions 'search' but doesn't disclose behavioral traits like whether this is a read-only operation, if it requires authentication, rate limits, pagination, error handling, or what the search returns (e.g., flight options, prices). For a complex search tool with no annotations, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise with a single sentence ('Search for multi-city flights.'). It's front-loaded and wastes no words, though this conciseness comes at the cost of completeness. Every word earns its place by stating the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multi-city flight search with 1 parameter containing nested objects), no annotations, and an output schema (which reduces need to describe returns), the description is incomplete. It lacks context on usage, behavior, and doesn't leverage the output schema to clarify purpose. For a search tool with rich schema but no annotations, more guidance is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the input schema has detailed descriptions for all parameters (e.g., 'Flight segments', 'Departure date (YYYY-MM-DD)'). The description adds no parameter information beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting, though the description doesn't compensate for the 0% coverage with any additional context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Search for multi-city flights' states the basic action (search) and resource (multi-city flights), but it's vague about scope and doesn't distinguish from sibling 'search_flights'. It doesn't specify what 'search' entails (e.g., finding available flights, prices, routes) or how multi-city differs from other flight types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus 'search_flights' or 'get_offer_details'. The description implies usage for multi-city flights but doesn't specify prerequisites, constraints (e.g., minimum segments), or alternatives. Without explicit when/when-not instructions, the agent lacks context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv1.0.0Aug 15, 2025
- First observedget_offer_details
- First observedsearch_flights
- First observedsearch_multi_city

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.8/5.0

Scored 2026-04-18 11:45 across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: get_offer_details retrieves details for a specific offer, search_flights handles standard flight searches, and search_multi_city handles multi-city itineraries. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case: get_offer_details, search_flights, and search_multi_city. The naming is predictable and readable throughout.

Tool Count3/5

With only 3 tools, the set feels thin for a flight search domain. While the core search functions are covered, typical operations like booking, managing reservations, or checking availability are missing, making the scope borderline minimal.

Completeness2/5

The toolset is significantly incomplete for flight operations. It lacks essential actions such as booking flights, canceling reservations, checking seat availability, or managing user profiles, which are critical for a functional flight service. Agents will face dead ends in common workflows.

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

GitHub Repository

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

Duffel A
io.github.pipeworx-io
Duffel MCP — live flight search + pricing via the Duffel Flights API (duffel.com)
Travel & Transportation Search
322
google-flightsOAuth
io.github.johnisanerd
Google Flights search data: fares, routes, stops, and price insights via a hosted MCP server.
Travel & Transportation Search
21
Ignav Flights A
io.github.gusgordon
Live flight prices and working booking links for AI agents and travel apps.
Travel & Transportation Search
221
World Airfares Flight Search A
com.worldairfares
Flight search MCP server providing search, pagination, and itinerary details for AI assistants.
Travel & Transportation Search
32

Related MCP Servers

Find Flights MCP Server
Travel & Transportation Search
guigas66
-
license
Not graded
quality
Not graded
maintenance
Enables searching and retrieving flight information using Duffel API, supporting one-way, round-trip, and multi-city queries with flexible search parameters.
Updated a year ago (2025-08-05 03:29 UTC)
-
Flight + Stay Search MCP
Travel & Transportation E-commerce & Retail Search
AkekaratP
F
license
C
quality
C
maintenance
Enables searching for flights (one-way, round-trip, multi-city) and hotels using the Duffel API, with support for filtering by cabin class, passengers, dates, and viewing accommodation reviews.
Updated a year ago (2025-05-06 06:37 UTC)
5
-
Flight + Stay Search MCP
Travel & Transportation E-commerce & Retail
clockworked247
F
license
C
quality
D
maintenance
Enables searching for flights (one-way, round-trip, multi-city) and hotels using the Duffel API, with support for detailed offer information, cabin class preferences, and guest reviews.
Updated a year ago (2025-04-16 09:14 UTC)
5
4
-
Duffel MCP Server
Travel & Transportation E-commerce & Retail
FortripEngineering
F
license
A
quality
Not graded
maintenance
Enables LLMs to search and book flights across 300+ airlines, manage travel orders, and search airports through the Duffel API with support for real-time pricing, multi-city trips, and flexible cabin classes.
Updated 10 months ago (2025-11-06 07:27 UTC)
6
-

Find Flights MCP Server

How it Works

Video Demo

Why This is Helpful

Features

Prerequisites

Getting Your Duffel API Key

Test Mode First (Recommended)

Getting a Live API Key

Security Note

Note on API Usage Limits

Installation

Installing via Smithery

Manual Installation

Configure as MCP Server

Deployment

Building

Debugging

Available Tools

1. Search Flights

2. Get Offer Details

3. Search Multi-City Flights

Use Cases

Some Example (But try it out yourself!)

Response Format

Error Handling

Contributing

License

Performance Notes

Cabin Classes

Available Tools

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches