flights-mcp

A flight-reconnaissance MCP server with one provider, one key, no KYC.

• Search flights with full pricing, every segment, every carrier, every layover
• Per-day price calendar (cheapest dates)
• Layover-quality scoring (connection-time risk, terminal change, overnight, airport reputation)
• Weighted multi-criteria ranking → "find the optimal flight path"
• Airport autocomplete

The one API you need

Steps:

1. Sign up at https://rapidapi.com/auth/sign-up (just email).
2. Visit https://rapidapi.com/apiheya/api/sky-scrapper and click Subscribe to Test.
3. Pick the Basic (Free) plan — no card required.
4. Copy X-RapidAPI-Key from the code-snippets panel.

Quick start

git clone <repo> flights-mcp
cd flights-mcp
python -m venv .venv
.venv\Scripts\activate
pip install -e .
copy .env.example .env
# open .env and paste your RAPIDAPI_KEY
python -m flights_mcp                       # stdio MCP server

Wire it into your MCP client

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "flights": {
      "command": "python",
      "args": ["-m", "flights_mcp"],
      "env": {
        "PYTHONPATH": "C:/path/to/flights-mcp/src",
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}

Full example: examples/claude_desktop_config.json.

Cursor / Continue / Cline / generic MCP clients

Most clients accept the mcp.json form. The ${RAPIDAPI_KEY} placeholder there is not a real key — the client substitutes it from your shell env or its secret store at launch. Real keys live in .env (gitignored) or your client's secret store.

Tools

Ranking model

Each criterion is normalised to [0, 1] across the candidate set (1 = best), then combined with caller-tunable weights:

Override per call:

find_optimal_path(
  origin="SFO", destination="SIN", departure_date="2026-07-04",
  weight_price=0.10, weight_layover_quality=0.40, weight_duration=0.30
)

Weights are auto-normalised, so any positive numbers work.

Layover heuristics

analyze_layovers and the layover_quality criterion penalise:

Plus penalty for overnight and terminal-change layovers. Small bonus for premium hubs (SIN, HKG, ICN, DOH, DXB, ZRH, AMS, CPH, HEL, MUC, FRA, ATL…); small penalty for delay-prone hubs (EWR, LGA, ORD, PHL, MIA, FCO, MAD).

Project layout

flights-mcp/
├── README.md
├── mcp.json                       # MCP manifest — env-var placeholders only
├── pyproject.toml
├── .env.example                   # one signup URL, one key
├── src/flights_mcp/
│   ├── __main__.py                # python -m flights_mcp
│   ├── server.py                  # FastMCP server, 7 tools
│   ├── config.py
│   ├── models.py                  # Airport / FlightOffer / Itinerary / Segment / Layover
│   ├── ranking.py                 # weighted multi-criteria scoring
│   ├── cache.py
│   └── providers/
│       ├── base.py
│       └── rapidapi.py            # Sky-Scrapper client + normaliser
├── examples/
│   ├── claude_desktop_config.json
│   └── sample_queries.md
└── tests/test_ranking.py

Development

pip install -e ".[dev]"
$env:PYTHONPATH = "src"
pytest                                       # Windows PowerShell
# PYTHONPATH=src pytest                      # macOS / Linux
python tests\_live_smoke.py                  # live RapidAPI call (uses one quota credit)

Security note

API keys live in .env (gitignored) or your MCP client's secret store. The mcp.json in this repo contains only ${VAR_NAME} placeholders — never literal keys.

License

MIT.