SkyOdyssey MCP

SkyOdyssey MCP exposes the SkyOdyssey flight engine as a Model Context Protocol server.

It is designed for AI clients (Claude Desktop, MCP Inspector, custom MCP hosts) that need:

• Cheapest destination exploration

• Multi-leg itinerary optimization

• Region/airport reference resources

Features

• MCP tools for flight search and itinerary optimization

• Shared core logic with SkyOdyssey-CLI (logic.py, airports.py)

• Country/airport/airline filters

• Budget-aware pruning (max_budget)

• Direct-flight filtering

• Multi-origin and flexible stay support for 3-leg itineraries

• SQLite caching (flights_cache.db, TTL 6h)

• Retry/backoff behavior for unstable provider responses

• Pydantic validation on itinerary outputs

Related MCP server: Award Flight Daily MCP Server

Tools Exposed

get_flights_on_date

Fetch one-way flights for a specific route/date.

Inputs:

• origin (IATA)

• destination (IATA)

• date (YYYY-MM-DD)

• adults (default 1)

• seat_type (default economy)

get_cheapest_destinations

Explore a region from one origin/date and return cheapest options.

Inputs:

• origin

• date

• region (default Europe)

• limit (default 15)

• adults

• seat_type

• excluded_countries

• excluded_airports

• direct_only

• include_airlines, exclude_airlines

• max_budget

find_cheapest_two_city_itinerary

Find cheapest 3-leg itinerary loops.

Inputs include:

• origin (single airport or list)

• start_date

• stay_days_1 / stay_days_2 (fixed int or [min, max])

• region

• limit_per_leg

• excluded_countries, excluded_airports

• max_itineraries

• force_different_countries

• direct_only

• return_origin (open-jaw)

• include_airlines, exclude_airlines

• max_budget

Guardrails:

• origin list max: 5

• limit_per_leg max: 30

• max_itineraries max: 100

• stay range window max width: 14 days (for each of stay_days_1 and stay_days_2)

Resources

• airports://regions → available regions

• airports://{region} → airport codes for a region

Requirements

• Python 3.10+

• Internet access (provider scraping via fast-flights)

Installation

From SkyOdyssey-MCP:

python -m pip install -r requirements.txt

Run the Server

python server.py

Server transport:

• stdio (configured in server.py)

Claude Desktop Example

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "skyodyssey": {
      "command": "python",
      "args": ["C:/absolute/path/to/SkyOdyssey/SkyOdyssey-MCP/server.py"]
    }
  }
}

Project Structure

• server.py — MCP server entrypoint and tool/resource registration

• logic.py — flight search, filtering, optimization, cache

• airports.py — regions, airport datasets, exclusion helpers

• requirements.txt — runtime dependencies

Troubleshooting

Import error for fast_flights

• Reinstall dependencies: python -m pip install -r requirements.txt

• Ensure your Python environment is the same one used to run server.py

Empty or partial results

• Provider instability/timeouts can happen; retry run

• Reduce search width (limit_per_leg) and/or constraints

• Relax filters (direct_only, exclusions, budget)

Cache issues

• Delete cache if needed:

  • Windows PowerShell: Remove-Item flights_cache.db

  • Windows cmd: del flights_cache.db

License

MIT License.