Flight Finder MCP

A production-grade MCP server that enables Claude to search and compare flights across multiple providers directly from your conversations.

Features

• Multi-Provider Search - Aggregates results from Skyscanner, Google Flights, and Kiwi.com

• Smart Caching - Reduces API calls with configurable TTL caching

• Parallel Queries - Searches multiple providers simultaneously with deduplication

• Flexible Filtering - Filter by price, stops, airlines, cabin class

• Result Analysis - Get recommendations for cheapest, fastest, and best value flights

Installation

Prerequisites

• Python 3.11+

• Claude Desktop or any MCP-compatible client

• At least one flight API key (Skyscanner, Google Flights, or Kiwi)

Setup

1. Clone the repository:

git clone https://github.com/yourusername/FlightFinderMCP.git
cd FlightFinderMCP

2. Install dependencies:

pip install -e .

3. Configure environment variables:

cp .env.example .env
# Edit .env and add your API key(s)

4. Add to Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "flight-finder": {
      "command": "flight-finder-mcp",
      "env": {
        "FLIGHT_FINDER_SKYSCANNER_API_KEY": "your_key_here"
      }
    }
  }
}

Usage

Once configured, you can ask Claude to search for flights naturally:

Claude will use the MCP tools to:

• Search across multiple flight providers

• Compare prices and flight times

• Filter by your preferences (non-stop, cabin class, etc.)

• Recommend the best options

Example Conversation

Available Tools

The server exposes three MCP tools:

• search_flights - Search for flights between airports

• get_cache_stats - View cache performance metrics

• clear_cache - Clear cached search results

Configuration

Key environment variables:

See .env.example for all available options.

Architecture

Built using clean architecture principles:

• Domain Layer - Flight entities, search criteria, value objects

• Application Layer - Use cases for search, filtering, recommendations

• Infrastructure Layer - API clients, caching, rate limiting

• Presentation Layer - MCP server handlers and schemas

Uses the Result monad pattern for error handling and Pydantic for validation.

Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# With coverage
pytest --cov=src/flight_finder

Code Quality

# Format code
black src tests
isort src tests

# Type checking
mypy src

# Linting
ruff check src tests

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.