Hut Reservation

Find, check, and book Swiss Alpine Club (SAC) huts straight from your AI agent — write-safe by default.

npm version npm downloads license MCP

A Model Context Protocol server that gives any MCP-capable agent (Claude, Codex, Cursor, …) the ability to search huts on hut-reservation.org, check exact-date availability, and prepare bookings and cancellations.

Ask your agent things like:

• "Find huts within 20 km of Zermatt that have space for 2 people on 12 July."
• "Is the Cabane du Mont Fort free next weekend?"
• "Draft a booking for the Britanniahütte for 2 nights and give me the confirmation link."
• "List my upcoming hut reservations."

Why write-safe? Bookings and cancellations never fire blind. By default the server prepares a draft and hands you a browser URL to confirm the final step yourself — so an agent can do all the searching and legwork without the risk of an accidental, hard-to-reverse reservation. Confirmed upstream writes are opt-in. See Safety model.

Quick start

npx hut-reservation-mcp

The server speaks MCP over stdio, so you normally don't run it by hand — you point your MCP client at it and let the client spawn it. Pick your client below.

claude mcp add hut-reservation -- npx -y hut-reservation-mcp

{
  "mcpServers": {
    "hut-reservation": {
      "command": "npx",
      "args": ["-y", "hut-reservation-mcp"]
    }
  }
}

codex mcp add hut-reservation -- npx -y hut-reservation-mcp

{
  "mcpServers": {
    "hut-reservation": {
      "command": "npx",
      "args": ["-y", "hut-reservation-mcp"],
      "env": {
        "HUT_RESERVATION_CACHE_DIR": "$HOME/.cache/hut-reservation-mcp"
      }
    }
  }
}

The package ships with a bundled hut catalog so search_huts and search_hut_availability work immediately without logging in. Availability lookups are also unauthenticated. You'll get a warning in results that the bundled catalog may be stale — run refresh_hut_catalog with credentials to update it. Booking, cancellation, listing your reservations, and refreshing the catalog require authentication. See Configuration & authentication.

Tools

All tool-facing dates use ISO YYYY-MM-DD. The server translates to the upstream Swiss DD.MM.YYYY format internally.

¹ Works without credentials using the bundled catalog. Results include a staleness warning; run refresh_hut_catalog with credentials to update. ² Requires a configured Nominatim-compatible geocoder (NOMINATIM_BASE_URL), but no hut-reservation.org login.

⚠️ Confirmation tools return a browser handoff URL by default. They only perform a real upstream write when experimental writes are explicitly enabled and a raw payload is supplied.

search_hut_availability checks every matched hut by default. Set maxCandidates only when you intentionally want a faster partial search; partial responses include truncated, totalCandidates, checkedCandidates, and a warning.

Suggested workflows

Find huts with availability (no login needed for steps 1–2)

1. search_huts → 2. search_hut_availability. The bundled catalog is used automatically if no local cache exists; watch for the staleness warning.
2. Optionally: authenticate → refresh_hut_catalog → repeat for the latest hut list.
3. For canton filters: configure a reverse geocoder → refresh_area_cache (no login needed).

Prepare a booking

1. Search huts + availability → 2. prepare_booking → 3. review the draft → 4. confirm_booking → 5. complete the browser handoff (unless experimental writes are enabled).

Prepare a cancellation

1. Authenticate → 2. list_bookings → 3. prepare_cancellation → 4. review the draft → 5. confirm_cancellation → 6. complete the browser handoff (unless experimental writes are enabled).

Safety model

High-risk upstream writes are intentionally conservative. The public SPA exposes preBook, submit, myReservations, reservationSummary, delete/{id}, and partial-cancellation-fee endpoints, but the full booking-form payload is not documented — so blind automated writes would be fragile and risky.

By default, confirm_booking and confirm_cancellation return a browser handoff URL instead of writing. A real write requires both:

• HUT_RESERVATION_EXPERIMENTAL_WRITES=true, and
• a caller-supplied raw payload.

Treat session cookies, XSRF tokens, passwords, and raw booking payloads as bearer credentials. Keep them in ignored local files, your MCP client's env config, or a secret manager. Never commit them.

Configuration & authentication

Do I need to authenticate?

No — searching works out of the box. The package bundles a hut catalog, and hut availability is a public endpoint, so you can find huts and check dates with zero setup. Add credentials only when you want fresher data or to touch your own reservations.

The bundled catalog only changes when huts open, close, or get renamed — rarely. Search results flag when it's getting old so your agent can suggest a refresh_hut_catalog.

Which auth mode?

⚠️ If you log in to hut-reservation.org via the Swiss Alpine Club (i.e. your account is an SAC account), you must use sac mode. The standard username/password flow only works for native hut-reservation.org accounts; an SAC-linked email will authenticate but the session is rejected as "Invalid Session". When in doubt, use sac.

standard — a native hut-reservation.org account (username + password):

HUT_RESERVATION_AUTH_MODE=standard
[email protected]
HUT_RESERVATION_PASSWORD=...

sac — an SAC account, via browser-session cookies. Log in at hut-reservation.org through SAC in your browser, then open DevTools → Application → Cookies → https://www.hut-reservation.org and copy the SESSION and XSRF-TOKEN values:

HUT_RESERVATION_AUTH_MODE=sac
HUT_RESERVATION_SESSION_COOKIE=...
HUT_RESERVATION_XSRF_TOKEN=...
# or, equivalently, both in one header:
# HUT_RESERVATION_COOKIE_HEADER="SESSION=...; XSRF-TOKEN=..."

SAC cookies expire — when catalog refresh starts failing with an auth error, grab fresh cookie values from the browser.

Setting these variables with the npx install

Because your MCP client (not your shell) spawns the server, set credentials in the client config rather than relying on a shell environment. Two options:

1. Inline in the client's env block (or -e KEY=val with claude mcp add):

{
  "mcpServers": {
    "hut-reservation": {
      "command": "npx",
      "args": ["-y", "hut-reservation-mcp"],
      "env": {
        "HUT_RESERVATION_AUTH_MODE": "sac",
        "HUT_RESERVATION_SESSION_COOKIE": "...",
        "HUT_RESERVATION_XSRF_TOKEN": "..."
      }
    }
  }
}

2. Point at a .env file by absolute path — keeps secrets out of the client config:

"env": { "HUT_RESERVATION_DOTENV_PATH": "/Users/me/.config/hut-reservation/.env" }

The server auto-loads .env from its working directory too, but under npx that directory is unpredictable, so prefer HUT_RESERVATION_DOTENV_PATH. Values from the env block override values from the .env file. See .env.example for a template, and treat cookies, tokens, and passwords as secrets — never commit them.

All environment variables

Reverse geocoder (optional, for canton filters)

NOMINATIM_BASE_URL=https://your-nominatim.example
NOMINATIM_USER_AGENT="hut-reservation-mcp/0.1.0 [email protected]"
NOMINATIM_MIN_INTERVAL_MS=1000

The server never uses public Nominatim implicitly. Configure an explicit provider and identifying User-Agent before calling refresh_area_cache. Follow the provider's usage policy, cache responses, and preserve OpenStreetMap attribution.

Troubleshooting

Develop from source

git clone https://github.com/domwoe/hut-reservation-mcp.git
cd hut-reservation-mcp
pnpm install
pnpm dev          # run over stdio from TypeScript source

Point a client at your local checkout:

claude mcp add hut-reservation -- pnpm --dir /absolute/path/to/hut-reservation-mcp dev
# or, for the built entrypoint:
pnpm build
claude mcp add hut-reservation -- node /absolute/path/to/hut-reservation-mcp/dist/index.js

Regenerating the bundled catalog

The package ships data/catalog.json so users can search without authenticating. Regenerate it before releasing a new version:

# Requires valid credentials in .env (standard or sac mode)
pnpm generate:catalog
# then commit data/catalog.json and bump the version

The hut catalog changes rarely (new huts open, names change). Regenerating once per release is sufficient.

Verification

pnpm typecheck
pnpm test
pnpm run smoke:mcp:source
pnpm build
pnpm run smoke:mcp:dist

Optional read-only live smoke test against upstream:

HUT_RESERVATION_LIVE_SMOKE=true pnpm smoke:read

Disclaimer

This is an unofficial, community project and is not affiliated with the Swiss Alpine Club (SAC) or hut-reservation.org. Use it responsibly and in line with the site's terms of service.