Skip to content
Back to search

flights-mcp

An MCP server to search for flights.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ravinahp--flights-mcp/badge.svg)](/listings/ravinahp--flights-mcp)

HTML

<a href="/listings/ravinahp--flights-mcp"><img src="/api/listings/ravinahp--flights-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing via Smithery

To install Find Flights for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ravinahp/travel-mcp):

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 253 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Find Flights MCP Server
  2. MCP server for searching and retrieving flight information using Duffel API.
  3. ## How it Works
  4. ![Flight](https://github.com/user-attachments/assets/3ee342a4-c2da-4d4e-a43c-79ae4590d893)
  5. ## Video Demo
  6. https://github.com/user-attachments/assets/c111aa4c-9559-4d74-a2f6-60e322c273d4
  7. ## Why This is Helpful
  8. While tools like Google Flights work great for simple trips, this tool shines when dealing with complex travel plans. Here's why:
  9. - **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
  10. - **Flexible Date Search**: Easily search across multiple days to find the best prices without manually checking each date
  11. - **Complex Itineraries**: Perfect for multi-city trips, one-stop flights, or when you need to compare different route options you can just ask!
  12. - **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.
  13. 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.
  14. ## Features
  15. - Search for flights between multiple destinations
  16. - Support for one-way, round-trip, and multi-city flight queries
  17. - Detailed flight offer information
  18. - Flexible search parameters (departure times, cabin class, number of passengers)
  19. - Automatic handling of flight connections
  20. - Search for flights within multiple days to find the best flight for your trip (slower)
  21. ## Prerequisites
  22. - Python 3.x
  23. - Duffel API Live Key
  24. ## Getting Your Duffel API Key
  25. 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.
  26. 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.
  27. ### Test Mode First (Recommended)
  28. 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:
  29. 1. Visit [Duffel's registration page](https://app.duffel.com/join)
  30. 2. Create an account (you can select "Personal Use" for Company Name)
  31. 3. Navigate to More > Developer to find your test API key (one is already provided)
  32. ### Getting a Live API Key
  33. To access real flight data, follow these steps:
  34. 1. In the Duffel dashboard, toggle "Test Mode" off in the top left corner
  35. 2. The verification process requires multiple steps - you'll need to toggle test mode off repeatedly:
  36. - First toggle: Verify your email address
  37. - Toggle again: Complete company information (Personal Use is fine)
  38. - Toggle again: Add payment information (required by Duffel but NO CHARGES will be made by this MCP server)
  39. - Toggle again: Complete any remaining verification steps
  40. - Final toggle: Access live mode after clicking "Agree and Submit"
  41. 3. Once fully verified, go to More > Developer > Create Live Token
  42. 4. Copy your live API key
  43. 💡 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.
  44. ⚠️ IMPORTANT NOTES:
  45. - Your payment information is handled directly by Duffel and is not accessed or stored by the MCP server
  46. - This MCP server is READ-ONLY - it can only search for flights, not book them
  47. - No charges will be made to your payment method through this integration
  48. - All sensitive information (including API keys) stays local to your machine
  49. - You can start with the test API key (`duffel_test`) to evaluate the functionality
  50. - The verification process may take some time - this is a standard Duffel requirement
  51. ### Security Note
  52. 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.
  53. ### Note on API Usage Limits
  54. - Check Duffel's current pricing and usage limits
  55. - Different tiers available based on your requirements
  56. - Recommended to review current pricing on their website
  57. ## Installation
  58. ### Installing via Smithery
  59. To install Find Flights for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ravinahp/travel-mcp):
  60. ```bash
  61. npx -y @smithery/cli install @ravinahp/travel-mcp --client claude
  62. ```
  63. ### Manual Installation
  64. Clone the repository:
  65. ```bash
  66. git clone https://github.com/ravinahp/flights-mcp
  67. cd flights-mcp
  68. ```
  69. Install dependencies using uv:
  70. ```bash
  71. uv sync
  72. ```
  73. Note: We use uv instead of pip since the project uses pyproject.toml for dependency management.
  74. ## Configure as MCP Server
  75. To add this tool as an MCP server, modify your Claude desktop configuration file.
  76. Configuration file locations:
  77. - MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
  78. - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
  79. Add the following configuration to your JSON file:
  80. ```json
  81. {
  82. "flights-mcp": {
  83. "command": "uv",
  84. "args": [
  85. "--directory",
  86. "/Users/YOUR_USERNAME/Code/flights-mcp",
  87. "run",
  88. "flights-mcp"
  89. ],
  90. "env": {
  91. "DUFFEL_API_KEY_LIVE": "your_duffel_live_api_key_here"
  92. }
  93. }
  94. }
  95. ```
  96. ⚠️ IMPORTANT:
  97. - Replace `YOUR_USERNAME` with your actual system username
  98. - Replace `your_duffel_live_api_key_here` with your actual Duffel Live API key
  99. - Ensure the directory path matches your local installation
  100. ## Deployment
  101. ### Building
  102. Prepare the package:
  103. ```bash
  104. # Sync dependencies and update lockfile
  105. uv sync
  106. # Build package
  107. uv build
  108. ```
  109. This will create distributions in the `dist/` directory.
  110. ## Debugging
  111. For the best debugging experience, use the MCP Inspector:
  112. ```bash
  113. npx @modelcontextprotocol/inspector uv --directory /path/to/find-flights-mcp run flights-mcp
  114. ```
  115. The Inspector provides:
  116. - Real-time request/response monitoring
  117. - Input/output validation
  118. - Error tracking
  119. - Performance metrics
  120. ## Available Tools
  121. ### 1. Search Flights
  122. ```python
  123. @mcp.tool()
  124. async def search_flights(params: FlightSearch) -> str:
  125. """Search for flights based on parameters."""
  126. ```
  127. Supports three flight types:
  128. - One-way flights
  129. - Round-trip flights
  130. - Multi-city flights
  131. Parameters include:
  132. - `type`: Flight type ('one_way', 'round_trip', 'multi_city')
  133. - `origin`: Origin airport code
  134. - `destination`: Destination airport code
  135. - `departure_date`: Departure date (YYYY-MM-DD)
  136. - Optional parameters:
  137. - `return_date`: Return date for round-trips
  138. - `adults`: Number of adult passengers
  139. - `cabin_class`: Preferred cabin class
  140. - `departure_time`: Specific departure time range
  141. - `arrival_time`: Specific arrival time range
  142. - `max_connections`: Maximum number of connections
  143. ### 2. Get Offer Details
  144. ```python
  145. @mcp.tool()
  146. async def get_offer_details(params: OfferDetails) -> str:
  147. """Get detailed information about a specific flight offer."""
  148. ```
  149. Retrieves comprehensive details for a specific flight offer using its unique ID.
  150. ### 3. Search Multi-City Flights
  151. ```python
  152. @mcp.tool(name="search_multi_city")
  153. async def search_multi_city(params: MultiCityRequest) -> str:
  154. """Search for multi-city flights."""
  155. ```
  156. Specialized tool for complex multi-city flight itineraries.
  157. Parameters include:
  158. - `segments`: List of flight segments
  159. - `adults`: Number of adult passengers
  160. - `cabin_class`: Preferred cabin class
  161. - `max_connections`: Maximum number of connections
  162. ## Use Cases
  163. ### Some Example (But try it out yourself!)
  164. You can use these tools to find flights with various complexities:
  165. - "Find a one-way flight from SFO to NYC on Jan 7 for 2 adults in business class"
  166. - "Search for a round-trip flight from LAX to London, departing Jan 8 and returning Jan 15"
  167. - "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"
  168. - "What is the cheapest flight from SFO to LAX from Jan 7 to Jan 15 for 2 adults in economy class?"
  169. - 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"
  170. ## Response Format
  171. The tools return JSON-formatted responses with:
  172. - Flight offer details
  173. - Pricing information
  174. - Slice (route) details
  175. - Carrier information
  176. - Connection details
  177. ## Error Handling
  178. The service includes robust error handling for:
  179. - API request failures
  180. - Invalid airport codes
  181. - Missing or invalid API keys
  182. - Network timeouts
  183. - Invalid search parameters
  184. ## Contributing
  185. [Add guidelines for contribution, if applicable]
  186. ## License
  187. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  188. ## Performance Notes
  189. - Searches are limited to 50 offers for one-way/round-trip flights
  190. - Multi-city searches are limited to 10 offers
  191. - Supplier timeout is set to 15-30 seconds depending on the search type
  192. ### Cabin Classes
  193. Available cabin classes:
  194. - `economy`: Standard economy class
  195. - `premium_economy`: Premium economy class
  196. - `business`: Business class
  197. - `first`: First class
  198. Example request with cabin class:
  199. ```json
  200. {
  201. "params": {
  202. "type": "one_way",
  203. "adults": 1,
  204. "origin": "SFO",
  205. "destination": "LAX",
  206. "departure_date": "2025-01-12",
  207. "cabin_class": "business" // Specify desired cabin class
  208. }
  209. }
  210. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.