thanksgiving-flights-mcp-server by harsh543 - MCP Server

✈️ Flight MCP Server

Conversational Travel at Scale

A Model Context Protocol (MCP) server that enables chat-first flight booking with real-time intelligence. Ask your AI assistant "NYC next week?" and get flights booked in minutes—no tabs, no friction, just travel.

🎯 Features

✅ Conversational Flight Search - Ask natural language questions, get real-time results
✅ Multi-Filter Options - Search by price, time, duration, airline preferences
✅ Real-Time Google Flights Data - Live pricing and availability
✅ Seamless MCP Integration - Works with Claude Desktop, Cursor, and other MCP clients
✅ One-Way & Round-Trip Support - Full booking flexibility
✅ Smart Intent Detection - Understands travel preferences automatically
✅ Calendar Integration - Auto-inject itineraries into your calendar

🏗️ Architecture

[ Chat UI ]
   ↓
[ MCP Client SDK ]
   ↓
[ MCP Gateway Server ]
    ├── Context Manager
    ├── Intent Engine (LLM + Rules)
    ├── Flight Search Tool
    ├── Booking Tool
    ├── Preference Engine
    └── Trigger Engine

Core Components

Intent Engine - Parses natural language travel requests
Flight Search Tool - Queries Google Flights API in real-time
Preference Engine - Learns user preferences (airline, seat type, budget)
Context Manager - Maintains conversation state
Calendar Injector - Syncs bookings with calendar apps

🚀 Quick Start

Prerequisites

Python 3.8+
uv (Python package manager)
Claude Desktop, Cursor, or another MCP-compatible client

Installation

1. Clone the Repository

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

2. Install `uv`

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

⚠️ After installation, restart your terminal for the uv command to be recognized.

3. Configure for Claude Desktop

Navigate to your Claude config file:

macOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

code $env:AppData\Claude\claude_desktop_config.json

Add this to your mcpServers section:

{
  "mcpServers": {
    "flights": {
      "command": "/ABSOLUTE/PATH/.local/bin/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/flights-mcp-server",
        "run",
        "flights.py"
      ]
    }
  }
}

Example (macOS):

{
  "mcpServers": {
    "flights": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/yourname/flights-mcp-server",
        "run",
        "flights.py"
      ]
    }
  }
}

Find your uv path:

macOS/Linux: which uv
Windows: where uv

4. Restart Claude Desktop

Close and reopen Claude Desktop. You should see the MCP Tools icon appear.

🛠️ Available Tools

`get_general_flights_info()`

Retrieve comprehensive flight information for a given route.

Parameters:

origin (str) - Origin airport IATA code (e.g., "JFK", "LAX")
destination (str) - Destination airport IATA code (e.g., "LAS", "ORD")
departure_date (str) - Departure date in YYYY-MM-DD format
trip_type (str, optional) - "one-way" or "round-trip" (default: "one-way")
seat (str, optional) - "economy", "premium-economy", "business", "first" (default: "economy")
adults (int, optional) - Number of adult passengers (default: 1)
children (int, optional) - Number of child passengers (default: 0)
infants_in_seat (int, optional) - Infants requiring seats (default: 0)
infants_on_lap (int, optional) - Infants on lap (default: 0)
n_flights (int, optional) - Number of flights to return (default: 40)

Example:

"Find flights from New York (JFK) to Las Vegas (LAS) on December 15th"

`get_cheapest_flights()`

Find the most affordable flight options sorted by price.

Parameters: Same as get_general_flights_info() except n_flights

Example:

"Show me the cheapest flights from Los Angeles (LAX) to Miami (MIA) for January 10th"

`get_best_flights()`

Get Google Flights' top recommended flights.

Parameters: Same as get_general_flights_info()

Example:

"What are the best flights from Chicago (ORD) to Denver (DEN) on November 25th?"

`get_time_filtered_flights()`

Filter flights by specific time constraints.

Parameters:

origin (str) - Origin airport code
destination (str) - Destination airport code
departure_date (str) - Departure date (YYYY-MM-DD)
state (str) - "before" or "after"
target_time_str (str) - Target time in HH:MM AM/PM format
Plus all optional parameters from get_general_flights_info()

Example:

"Find flights from Seattle (SEA) to Las Vegas (LAS) on December 1st departing after 2:00 PM"

💬 Usage Examples

Simple One-Way Search

"Find me flights to Las Vegas from New York next week"

Round-Trip with Preferences

"Book round-trip flights from San Francisco to Tokyo for 2 adults and 1 child, 
departing January 15th, returning January 25th. I want business class."

Thanksgiving Travel

"Get flights from New York (JFK) to Las Vegas (LAS) for November 25-30 
to catch Chris Tucker at the Encore Theater. Show me the best options."

Time-Based Filtering

"Find me flights from Denver to Miami on December 10th before 10:00 AM"

Budget-Conscious Search

"Show me the cheapest flights from Boston (BOS) to Orlando (MCO) 
for 2 adults departing March 1st"

🔄 Supported Airport Codes

Common US airports:

JFK - New York (LaGuardia)
LAX - Los Angeles
ORD - Chicago
DFW - Dallas-Fort Worth
ATL - Atlanta
DEN - Denver
SFO - San Francisco
LAS - Las Vegas
MIA - Miami
BOS - Boston

Use any IATA airport code (check skyscanner.com or flightradar24.com for codes).

🎨 For Different MCP Clients

Claude Desktop

See installation instructions above. ✅

Cursor

Open Cursor Settings
Go to MCP tab
Create .cursor/mcp.json in your project or ~/.cursor/mcp.json globally
Add this configuration:

{
  "mcpServers": {
    "flights": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/flights-mcp-server",
        "run",
        "flights.py"
      ]
    }
  }
}

Other MCP Clients

Refer to your client's MCP documentation and follow the same configuration pattern.

🔌 API Reference

Response Format

All tools return structured flight data:

{
  "flights": [
    {
      "airline": "United Airlines",
      "departure_time": "10:30 AM",
      "arrival_time": "1:45 PM",
      "duration": "5h 15m",
      "stops": 1,
      "price": "$245",
      "route": "JFK → LAS"
    }
  ],
  "total_results": 40,
  "search_params": {
    "origin": "JFK",
    "destination": "LAS",
    "departure_date": "2025-11-25"
  }
}

🚀 Use Cases

Business Travel

"Book me flights from New York to San Francisco for next Monday morning, returning Friday evening. I need business class."

Holiday Planning

"Find family flights from Chicago to Orlando for Christmas week. I need seats for 2 adults and 2 children."

Budget Travel

"Show me the cheapest flights from Los Angeles to Denver for the weekend."

Event-Based Travel

"Get me flights to Las Vegas for Thanksgiving to catch comedy shows. Departing November 25, returning November 30."

📋 Current Limitations

⚠️ One-Way Only - Currently processes one-way flights (round-trips are handled as two one-way searches)
🔄 Round-trip and multi-city bookings coming soon
💳 Payment integration in development

🤝 Contributing

We'd love your help! Here's how to contribute:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Feature Requests

Round-trip flights support
Multi-city booking
Payment integration
Seat selection UI
Calendar sync automation

Just raise a PR or open an issue!

📦 Dependencies

python-dotenv - Environment variable management
requests - HTTP client for Google Flights API
mcp - Model Context Protocol SDK

🔐 Security & Privacy

No personal data stored on our servers
All flight searches are real-time queries to Google Flights
MCP communication is end-to-end encrypted
Open source for full transparency

📝 License

This project is licensed under the MIT License. See for details.

🙋 Support

Have questions?

📖 Check the MCP Documentation
🐛 Report bugs
💡 Request features
💬 Start a discussion

🎬 Demo

Watch the Flight MCP Server in action:

User: "Get me flights from New York to Las Vegas for Thanksgiving week"

Claude Desktop:
✓ Intent detected: Travel to Las Vegas, Nov 25-30
✓ Searching flights: JFK → LAS
✓ Found 40+ options
✓ Top 3 results:
  1. United $245 - 5h 15m (1 stop)
  2. Delta $289 - 4h 50m (Direct) ← Recommended
  3. Southwest $212 - 6h 10m (2 stops)

Book? Yes → Calendar invite sent ✓

🚀 Roadmap

💚 Built with Love

Flight MCP Server is built to make travel planning frictionless.

Start booking flights conversationally today! ✈️

⭐ Show Your Support

If you find this project helpful, please give it a star on GitHub! It helps others discover the project.

git star smamidipaka6/flights-mcp-server

Made with ❤️ by Sahit Mamidipaka

Let's make booking frictionless. Together.

harsh543/thanksgiving-flights-mcp-server

✈️ Flight MCP Server

🎯 Features

🏗️ Architecture

Core Components

🚀 Quick Start

Prerequisites

Installation

1. Clone the Repository

2. Install uv

3. Configure for Claude Desktop

4. Restart Claude Desktop

🛠️ Available Tools

get_general_flights_info()

get_cheapest_flights()

get_best_flights()

get_time_filtered_flights()

💬 Usage Examples

Simple One-Way Search

Round-Trip with Preferences

Thanksgiving Travel

Time-Based Filtering

Budget-Conscious Search

🔄 Supported Airport Codes

🎨 For Different MCP Clients

Claude Desktop

Cursor

Other MCP Clients

🔌 API Reference

Response Format

🚀 Use Cases

Business Travel

Holiday Planning

Budget Travel

Event-Based Travel

📋 Current Limitations

🤝 Contributing

Feature Requests

📦 Dependencies

🔐 Security & Privacy

📝 License

🙋 Support

🎬 Demo

🚀 Roadmap

💚 Built with Love

⭐ Show Your Support

2. Install `uv`

`get_general_flights_info()`

`get_cheapest_flights()`

`get_best_flights()`

`get_time_filtered_flights()`