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"

Related MCP server: Jinko Hotel Booking MCP Server

Tools

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.