perun-mcp

An MCP (Model Context Protocol) server for Perun.search — a Polish trip planner that finds cheap flights and pairs each destination with the nearest InPost parcel locker and hotel, so you can ship your luggage ahead instead of paying airline baggage fees.

This is a thin HTTP client: it contains no trip-planning logic of its own. Every tool call is a plain GET request against the public API at https://perunsearch.tours/api, and the JSON response is returned as-is to your agent. All flight/locker/pricing logic lives server-side.

Quickstart

git clone https://github.com/swiru95/perun-mcp
cd perun-mcp
pip install -r requirements.txt   # or: uv pip install -r requirements.txt

Register with Claude Code

claude mcp add perun -- python /path/to/perun-mcp/server.py

Claude Desktop / other stdio clients

Add to your MCP client config:

{
  "mcpServers": {
    "perun": {
      "command": "python",
      "args": ["/path/to/perun-mcp/server.py"]
    }
  }
}

Pointing at a different API base (optional)

By default the server calls https://perunsearch.tours/api. Override with:

export PERUN_API_BASE="https://your-host/api"

Tools

Tool	Description
list_origin_airports()	List departure airports (IATA, city, country).
plan_trip(airport, date, nights=7, luggage="on_arrival", parcel="B", trip="one_way", domestic=False, dest=None, return_date=None)	Cheapest flights from airport plus nearby InPost lockers and hotels at each destination. trip="round_trip" requires return_date.
route_fares(airport, dest, date, return_date=None)	Live fare lookup for one specific route/date (all covered airlines). Budget-limited server-side and cached — use sparingly.
list_destinations(airport)	LOT domestic "fly to" destinations from a given Polish airport.
popular_routes()	Currently popular/recently priced routes, plus fare-lookup budget status.

All tools raise a clear error (with the API's error message, when present) on a non-200 response.

Disclaimer

Prices, availability, and locker/hotel data returned by these tools are indicative only and sourced live from third parties (airlines, InPost, hotel providers) — they are not guaranteed and may change before you book. Booking links included in results point to the airline/provider directly; Perun.search does not process payments or bookings itself.

See the full terms at perunsearch.tours/regulamin.html.

Fair use

This server calls the public Perun.search API. Please be a good citizen: avoid hammering route_fares (it triggers live, budget-limited third-party lookups) and prefer plan_trip for broad searches.

License

MIT — see LICENSE.