Guesty MCP Server (@hostautomation/guesty-mcp)

Ein Model-Context-Protocol-(MCP)-Server für die Guesty Open API — Eigenentwicklung von HouseAutomation. Macht Guesty-Daten (Reservierungen, Listings, Kalender/ Preise, Gäste, Tasks, Owner, Accounting) in Claude Code, Claude Desktop und jedem MCP-Client als Werkzeuge nutzbar.

Bewusst selbst gebaut statt das Community-Paket zu nutzen — gleiche saubere Architektur wie der Smoobu-Server, ohne Telemetrie, read-only by default, volle Kontrolle über die Lieferkette. Lizenz: MIT. Vergleich/Community-Alternative: siehe ../guesty/README.md.

Funktionsumfang

15 Tools — 11 Lese-Tools (immer) + 4 Schreib-Tools (nur per Opt-in):

| Bereich | Lesen | Schreiben (Opt-in) | |---|---|---| | Reservierungen | guesty_list_reservations, guesty_get_reservation | guesty_update_reservation | | Listings | guesty_list_listings, guesty_get_listing | guesty_update_listing_prices | | Kalender/Preise | guesty_get_calendar | guesty_update_calendar | | Gäste | guesty_list_guests, guesty_get_guest | — | | Tasks | guesty_list_tasks | guesty_create_task | | Owner | guesty_list_owners | — | | Accounting | guesty_get_journal_entries | — | | Messaging | guesty_list_conversations | — |

Sicherheitskonzept

• Read-only by default. Schreib-Tools werden nur registriert, wenn der Server mit GUESTY_ALLOW_WRITES=true startet.
• Keine Telemetrie. Der Server sendet nichts an Dritte — nur an die Guesty-API.
• Credentials nur via Env, nie im Code/Repo.
• OAuth2-Token-Caching: Guesty erlaubt nur ~5 Token-Anfragen pro Key/24 h. Der Server holt den Token einmal und cached ihn prozessweit (auch im HTTP-Modus), refresht 5 min vor Ablauf und erneuert bei 401/403 einmalig.

Voraussetzungen

• Node.js ≥ 18
• Guesty-Account mit Professional-Plan (für API-Zugang)
• Claude Code oder Claude Desktop

Schritt 1 – Guesty-Zugangsdaten erstellen

1. In Guesty einloggen (app.guesty.com).
2. Settings → API → neue API-Application mit Scope open-api anlegen.
3. Client ID und Client Secret kopieren (Secret wird nur einmal angezeigt).

Schnelltest (ersetze ID/SECRET):

curl -s -X POST https://open-api.guesty.com/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{"clientId":"ID","clientSecret":"SECRET"}'

Kommt ein access_token zurück → Zugangsdaten passen.

Schritt 2 – Installieren

Option A – aus npm (empfohlen, nichts zu bauen): nur Node ≥ 18; der Server wird beim Einbinden automatisch per npx geladen (Schritt 3).

Option B – aus dem Quellcode:

cd guesty-mcp
npm install
npm run build
npm test        # URL-Test + Smoke-Test, erwartet PASS (11 / 15 / 4)

Schritt 3 – In Claude Code einbinden

Ersetze DEINE_ID / DEIN_SECRET.

claude mcp add guesty --scope user \
  --env GUESTY_CLIENT_ID=DEINE_ID \
  --env GUESTY_CLIENT_SECRET=DEIN_SECRET \
  -- npx -y @hostautomation/guesty-mcp

Danach /mcp in Claude Code → guesty sollte verbunden sein. Version pinnen: npx -y @hostautomation/[email protected].

JSON-Variante (~/.claude.json bzw. .mcp.json):

{
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@hostautomation/guesty-mcp"],
      "env": {
        "GUESTY_CLIENT_ID": "DEINE_ID",
        "GUESTY_CLIENT_SECRET": "DEIN_SECRET"
      }
    }
  }
}

Variante B – aus dem Quellcode: statt -- npx … im guesty-mcp-Ordner -- node "$(pwd)/build/index.js".

Schritt 3b – In Claude Desktop einbinden

Datei claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) mit demselben mcpServers-Block (JSON-Variante) ergänzen und Claude Desktop neu starten.

Benutzung

• „Zeig mir die bestätigten Guesty-Reservierungen mit Check-in im Juli 2026."
• „Welche Listings habe ich (ohne MTL_CHILD-Sub-Units)?"
• „Wie ist Preis & Verfügbarkeit für Listing <id> vom 2026-08-01 bis 2026-08-31?"
• „Liste die offenen Tasks."

Mit aktiviertem Schreibzugriff zusätzlich:

• „Lege für Listing <id> eine Reinigungs-Task am 2026-07-20 10:00 an."
• „Setze für Listing <id> vom 2026-12-20 bis 2026-12-27 den Preis auf 180 und minNights 3."

Tool-Referenz

| Tool | Typ | Guesty-Endpoint | Wichtige Parameter | |---|---|---|---| | guesty_list_reservations | read | GET /v1/reservations | limit, skip, sort, fields, filters (JSON) | | guesty_get_reservation | read | GET /v1/reservations/{id} | id, fields | | guesty_list_listings | read | GET /v1/listings | limit, skip, fields, filters | | guesty_get_listing | read | GET /v1/listings/{id} | id, fields | | guesty_get_calendar | read | GET /v1/availability-pricing/api/calendar/listings/{id} | listingId, from, to | | guesty_list_guests | read | GET /v1/guests | limit, skip, fields, filters | | guesty_get_guest | read | GET /v1/guests/{id} | id, fields | | guesty_list_tasks | read | GET /v1/tasks | limit, skip | | guesty_list_owners | read | GET /v1/owners | limit, skip | | guesty_get_journal_entries | read | GET /v1/accounting/journal-entries | from, to, listingId, type | | guesty_list_conversations | read | GET /v1/communication/conversations | limit, skip | | guesty_update_reservation | write | PUT /v1/reservations/{id} | id, guestsCount, plannedArrival/Departure | | guesty_update_listing_prices | write | PUT /v1/listings/{id} | id, prices{} | | guesty_update_calendar | write | PUT /v1/availability-pricing/api/calendar/listings/{id} | listingId, from, to, price?, minNights? | | guesty_create_task | write | POST /v1/tasks | title, listingId?, startTime?, checklist[]? … |

Guesty-Eigenheiten (im Server/den Beschreibungen berücksichtigt):

• IDs sind Strings (24-stellige Hex-IDs), keine Zahlen.
• Pagination: limit + skip; Antwort {results, count, limit, skip}.
• Fürs Invoicing money.fareAccommodationAdjusted statt fareAccommodation.
• Bei Preis-Faktoren MTL_CHILD-Sub-Units ausschließen (unterstützen keine Faktoren).
• Rate-Limit: max. 15 gleichzeitige Requests; bei 429 Retry-After beachten.

Schreibzugriff aktivieren

claude mcp add guesty --scope user \
  --env GUESTY_CLIENT_ID=DEINE_ID \
  --env GUESTY_CLIENT_SECRET=DEIN_SECRET \
  --env GUESTY_ALLOW_WRITES=true \
  -- npx -y @hostautomation/guesty-mcp

Empfehlung: Erst read-only testen, dann Schreibzugriff auf einem Test-Listing.

Optional: als HTTP-Server hosten

MCP_TRANSPORT=http \
  PORT=8788 \
  MCP_HTTP_HOST=0.0.0.0 \
  MCP_HTTP_AUTH_TOKEN=ein-langes-zufallstoken \
  MCP_HTTP_ALLOWED_HOSTS=dein-host.example \
  GUESTY_CLIENT_ID=DEINE_ID GUESTY_CLIENT_SECRET=DEIN_SECRET \
  node build/index.js
# Endpoint: POST http://<host>:8788/mcp · Health: GET /health

Default-Bind ist 127.0.0.1; ohne MCP_HTTP_AUTH_TOKEN warnt der Server, dass der Endpoint unauthentifiziert ist. Für öffentliches Hosting immer TLS + Token. Der OAuth-Token wird prozessweit gecached, also auch im HTTP-Modus nicht pro Request neu geholt.

Veröffentlichen auf npm (für Maintainer)

Unter der Organisation @hostautomation (öffentlich):

cd guesty-mcp
npm login
npm test
npm publish

publishConfig.access = public ist gesetzt. Voraussetzung: npm-Org hostautomation existiert und dein Account hat Publish-Recht.

DSGVO-Hinweis

Reservierungs-/Gästedaten sind personenbezogene Daten; Guesty ist US-basiert. Beim Nutzen fließen Gastdaten an Guesty (US-Sub-Prozessor) und an den KI-Anbieter (Anthropic). Praktisch: nur kommerziellen Claude-Tarif mit AVV, Datenminimierung via fields, und Guesty + Anthropic als Auftragsverarbeiter ins Verzeichnis von Verarbeitungstätigkeiten aufnehmen. Mehr: ../docs/apaleo-compliance.md.

Vorteil gegenüber dem Community-Paket: keine undisclosed Telemetrie — die einzige Datenabgabe ist die an Guesty selbst.

Fehlerbehebung

| Symptom | Ursache / Lösung | |---|---| | GUESTY_CLIENT_ID and GUESTY_CLIENT_SECRET must both be set | Env-Variablen fehlen in der MCP-Config. | | Guesty token request failed (401/403 …) | Client-ID/Secret falsch oder Scope ≠ open-api. | | Guesty API 429 … | Rate-Limit — kurz warten (Retry-After). | | 500 Integration not found | Noch keine Direkt-/Manual-Buchung — eine Test-Reservierung in Guesty anlegen. | | Schreib-Tools fehlen | GUESTY_ALLOW_WRITES=true nicht gesetzt (gewollt). | | Server nicht in /mcp | Claude-Code-Sitzung neu starten. |

Architektur

src/
├── index.ts          # Einstieg: stdio (default) oder http
├── server.ts         # baut den McpServer, registriert Tools
├── http.ts           # optionaler gehärteter Streamable-HTTP-Transport
├── config.ts         # Env-Parsing, Read-only-Flag, Host-Root-Normalisierung
├── guesty-client.ts  # OAuth2-Token-Cache (prozessweit) + HTTP-Schicht
└── tools/            # ein Modul je Bereich, Writes per Flag gegated
    ├── schemas.ts  shared.ts
    ├── reservations.ts  listings.ts  calendar.ts  guests.ts
    ├── tasks.ts  owners.ts  accounting.ts  communications.ts
    └── index.ts

Datenquelle der API-Abbildung: Guesty Open API (open-api-docs.guesty.com).