SkyOdyssey

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

---

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.