Fast Flights MCP Server

An MCP (Model Context Protocol) server that wraps the fast-flights library to provide AI agents with powerful flight search and analysis capabilities.

Features

This MCP server provides AI agents with tools to:

• Search Flights: Find available flights between airports on specific dates
• Find Best Price: Identify the cheapest flight option for a route
• Find Shortest Duration: Locate the fastest flight option
• Compare Flights: Get comprehensive analysis of all flight options
• Filter Flights: Apply custom criteria (price, duration, stops) to narrow down results

Quick Start

Installation

# Install uv package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Test the server
uv run python src/main.py

Local Testing

# Test the server configuration
uv run python test_mcp_server.py

# Run functional tests (searches real flights)
uv run python tests/test_server.py

Note: Running uv run main directly will show a JSON-RPC error - this is expected! MCP servers communicate via JSON-RPC and need to be run by an MCP client (like Claude Desktop or Dedalus), not directly from the terminal.

Available Tools

1. search_flights

Search for flights between two airports on a specific date.

Parameters:

• date (required): Flight date in YYYY-MM-DD format (e.g., "2025-01-01")
• from_airport (required): Departure airport code (e.g., "LAX", "JFK", "TPE")
• to_airport (required): Arrival airport code (e.g., "SFO", "LHR", "MYJ")
• adults (optional): Number of adult passengers (default: 1)
• children (optional): Number of child passengers (default: 0)
• infants_in_seat (optional): Number of infants in seat (default: 0)
• infants_on_lap (optional): Number of infants on lap (default: 0)
• max_results (optional): Maximum number of flights to return (default: 10)

Returns: Flight search results with pricing, duration, stops, and more.

2. find_best_price

Find the cheapest flight option for a route and date.

Parameters: Same as search_flights (except max_results)

Returns: Details of the cheapest flight with price comparisons.

3. find_shortest_duration

Find the flight with the shortest travel time.

Parameters: Same as search_flights (except max_results)

Returns: Details of the fastest flight with duration comparisons.

4. compare_flight_options

Get a comprehensive comparison of all available flight options.

Parameters: Same as search_flights (except max_results)

Returns: Analysis including:

• Cheapest flight
• Fastest flight
• Recommended options (flagged as "best" by the search engine)
• Statistics (average price, average duration, price ranges)
• Direct flight availability

5. filter_flights_by_criteria

Filter flights based on specific criteria.

Parameters:

• All parameters from search_flights PLUS:
• max_price (optional): Maximum price per person
• max_duration (optional): Maximum duration in minutes
• max_stops (optional): Maximum number of stops
• direct_only (optional): Show only direct flights (default: False)

Returns: Filtered flight results matching your criteria.

Usage Examples

Example 1: Basic Flight Search

from dedalus_labs import AsyncDedalus, DedalusRunner

async def search_example():
    client = AsyncDedalus(api_key="your-api-key")
    runner = DedalusRunner(client)

    result = await runner.run(
        input="Find flights from LAX to SFO on 2025-01-15 for 2 adults",
        model="claude-3-5-sonnet-20241022",
        mcp_servers=["your-org/fast-flights-mcp"]
    )

    print(result.final_output)

Example 2: Find Best Price

result = await runner.run(
    input="What's the cheapest flight from New York (JFK) to London (LHR) on March 1st, 2025?",
    model="openai/gpt-4",
    mcp_servers=["your-org/fast-flights-mcp"]
)

Example 3: Compare Options

result = await runner.run(
    input="Compare all flight options from TPE to MYJ on 2025-01-01. Show me the cheapest, fastest, and recommended flights.",
    model="claude-3-5-sonnet-20241022",
    mcp_servers=["your-org/fast-flights-mcp"]
)

Example 4: Filter Flights

result = await runner.run(
    input="Find direct flights from LAX to JFK on 2025-02-14 under $300 per person",
    model="openai/gpt-4",
    mcp_servers=["your-org/fast-flights-mcp"]
)

Project Structure

fast-flights-mcp/
├── main.py              # Entry point for Dedalus
├── pyproject.toml       # Package configuration
├── requirements.txt     # Dependencies
├── src/
│   ├── __init__.py     # Package marker
│   └── main.py         # MCP server implementation
└── tests/
    └── test_server.py  # Test script

Using with Claude Desktop (Local Testing)

To test your MCP server with Claude Desktop:

1. Find your Claude Desktop config file:

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

2. Add the server configuration:

{
  "mcpServers": {
    "fast-flights": {
      "command": "uv",
      "args": ["run", "main"],
      "cwd": "/Users/mikey/repos/fast-flights-mcp"
    }
  }
}

3. Restart Claude Desktop

4. You should see a 🔌 icon indicating MCP servers are connected

5. Try asking Claude:

   • "Find me the cheapest flight from LAX to SFO on January 20th"
   • "What's the fastest flight from New York to London on March 1st?"
   • "Compare flight options from TPE to MYJ"

Deploy to Dedalus

Prerequisites

1. Install Dedalus CLI:

pip install dedalus-labs

2. Authenticate:

dedalus login

Deployment

# Deploy to Dedalus
dedalus deploy . --name "fast-flights-mcp"

Using the Deployed Server

from dedalus_labs import AsyncDedalus, DedalusRunner

async def main():
    client = AsyncDedalus(api_key="your-api-key")
    runner = DedalusRunner(client)

    result = await runner.run(
        input="Find me the cheapest flight from LAX to NYC on January 20th",
        model="claude-3-5-sonnet-20241022",
        mcp_servers=["your-org/fast-flights-mcp"]
    )

    print(result.final_output)

How It Works

1. AI Agent Request: Your AI agent receives a natural language request about flights
2. Tool Selection: The MCP framework identifies which flight search tool to use
3. API Call: The server calls the fast-flights library with appropriate parameters
4. Data Processing: Results are formatted and analyzed
5. Response: Structured flight data is returned to the AI agent
6. Natural Language: The AI formats the results into a user-friendly response

Flight Data Fields

Each flight in the results includes:

• name: Airline and flight number
• departure: Departure time
• arrival: Arrival time
• departure_time_ahead: Time until departure (if available)
• arrival_time_ahead: Time until arrival (if available)
• duration: Total flight duration in minutes
• stops: Number of stops (0 = direct)
• price: Price per person
• is_best: Whether this flight is flagged as a recommended option
• delay: Delay information (if available)

Airport Codes

Use standard IATA airport codes:

• LAX - Los Angeles International
• JFK - John F. Kennedy International (New York)
• SFO - San Francisco International
• LHR - London Heathrow
• TPE - Taiwan Taoyuan International
• MYJ - Matsuyama Airport (Japan)

Full list: https://en.wikipedia.org/wiki/IATA_airport_code

Troubleshooting

Issue: "No flights found"

• Check that airport codes are valid IATA codes
• Verify the date is in the future and in YYYY-MM-DD format
• Ensure the route is commonly served

Issue: Server won't start

• Make sure all dependencies are installed: uv sync
• Check Python version: python --version (requires 3.10+)
• Verify the fast-flights library is working: uv run python -c "import fast_flights; print('OK')"

Issue: Deployment fails

• Ensure pyproject.toml is properly configured
• Check that main.py exists at the root level
• Verify all dependencies are listed in requirements.txt

Advanced Usage

Multi-Stage Flight Planning

# Stage 1: Find cheapest option
result1 = await runner.run(
    input="Find the cheapest flight from LAX to NYC on Jan 20",
    model="openai/gpt-4o-mini",
    mcp_servers=["your-org/fast-flights-mcp"]
)

# Stage 2: Compare with fastest option
result2 = await runner.run(
    input=f"Based on this cheapest option: {result1.final_output}, now compare it with the fastest flight for the same route and date",
    model="claude-3-5-sonnet-20241022",
    mcp_servers=["your-org/fast-flights-mcp"]
)

# Stage 3: Make recommendation
result3 = await runner.run(
    input=f"Based on these options: {result2.final_output}, recommend the best choice for a business traveler who values time over cost",
    model="openai/gpt-4"
)

Batch Processing

routes = [
    ("LAX", "JFK", "2025-01-20"),
    ("LAX", "SFO", "2025-01-21"),
    ("JFK", "LHR", "2025-01-22")
]

tasks = []
for from_airport, to_airport, date in routes:
    task = runner.run(
        input=f"Find best price from {from_airport} to {to_airport} on {date}",
        model="openai/gpt-4o-mini",
        mcp_servers=["your-org/fast-flights-mcp"]
    )
    tasks.append(task)

results = await asyncio.gather(*tasks)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Resources

• fast-flights Library
• MCP Documentation
• Dedalus Platform

Support

For issues or questions:

• Open an issue on GitHub
• Check the fast-flights documentation
• Review MCP server examples

---

Built with ❤️ using the Model Context Protocol