# perun-mcp

An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for
[Perun.search](https://perunsearch.tours) — 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

```bash
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

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

### Claude Desktop / other stdio clients

Add to your MCP client config:

```json
{
  "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:

```bash
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](https://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](LICENSE).