@hostautomation/smoobu-mcp

v0.1.0

Published

4 days ago

Model Context Protocol (MCP) server for the Smoobu vacation-rental PMS API. Lets Claude read and (optionally) write apartments, reservations, rates and guest messages.

0High
0Medium
0Low

sandiego.cctj

mcp model-context-protocol smoobu pms vacation-rental claude ai

Smoobu MCP Server

Ein Model-Context-Protocol-(MCP)-Server für die Smoobu Ferienwohnungs-/PMS-API. Er macht Smoobu-Daten (Apartments, Reservierungen, Preise/Verfügbarkeit, Gast-Nachrichten) in Claude Code, Claude Desktop und jedem anderen MCP-fähigen Client als Werkzeuge nutzbar.

Eigenentwicklung von HouseAutomation — es gibt (Stand Juni 2026) keinen offiziellen Smoobu-MCP. Lizenz: MIT.

Inhalt

Funktionsumfang

15 Tools, aufgeteilt in 10 Lese-Tools (immer verfügbar) und 5 Schreib-Tools (nur nach ausdrücklicher Freigabe):

| Bereich | Lesen | Schreiben (Opt-in) | |---|---|---| | Konto | smoobu_get_account | — | | Apartments | smoobu_list_apartments, smoobu_get_apartment | — | | Reservierungen | smoobu_list_reservations, smoobu_get_reservation | smoobu_create_reservation, smoobu_update_reservation, smoobu_cancel_reservation | | Preise/Verfügbarkeit | smoobu_get_rates, smoobu_check_availability | smoobu_update_rates | | Nachrichten | smoobu_list_messages | smoobu_send_guest_message | | Gäste | smoobu_list_guests, smoobu_get_guest | — |

Sicherheitskonzept

Standardmäßig ist der Server read-only. Die fünf schreibenden Tools (Buchung anlegen/ändern/stornieren, Preise setzen, Gast-Nachricht senden) werden nur registriert, wenn der Server mit SMOOBU_ALLOW_WRITES=true startet. So kann eine versehentliche Änderung an Live-Buchungen nicht passieren, solange du Schreibzugriff nicht bewusst einschaltest.

Weitere Schutzmaßnahmen:

Der API-Key wird ausschließlich aus einer Environment-Variable gelesen, nie im Code oder in einer eingecheckten Datei gespeichert.
Schreib-Tools tragen den Zusatz (WRITE) im Titel; das Storno-Tool ist als destructive annotiert, sodass der Client eine Bestätigung verlangen kann.
Jeder Request hat ein Timeout; API-Fehler werden sauber als Tool-Fehler zurückgegeben, statt den Server abstürzen zu lassen.

Voraussetzungen

Node.js ≥ 18 (node --version)
Ein Smoobu-Account mit aktiviertem API-Zugang
Claude Code oder Claude Desktop

Schritt 1 – Smoobu-API-Key holen

In Smoobu einloggen → Einstellungen → „Smoobu API" / Für Entwickler (engl. Settings → For Developers).
API-Key generieren und kopieren.

Schnelltest mit curl (ersetze DEIN_KEY):

curl https://login.smoobu.com/api/me \
  -H "Api-Key: DEIN_KEY" \
  -H "Cache-Control: no-cache"

Antwort = dein Konto (id, firstName, lastName, email) → Key funktioniert.

Schritt 2 – Installieren

Zwei Wege – für die meisten reicht Option A:

Option A – aus npm (empfohlen, nichts zu bauen): Du brauchst nur Node.js ≥ 18. Der Server wird beim Einbinden automatisch per npx geladen (siehe Schritt 3) – hier ist nichts weiter zu tun.

Option B – aus dem Quellcode (für Entwicklung/Anpassungen):

cd smoobu-mcp
npm install
npm run build      # erzeugt build/index.js
npm test           # optional: Build + URL-Test + Smoke-Test

npm test muss URL test: PASS … und am Ende RESULT: PASS (expected 10 / 15 / 5) ausgeben.

Schritt 3 – In Claude Code einbinden

Ersetze DEIN_KEY durch deinen Smoobu-API-Key.

Variante A – aus npm (empfohlen):

claude mcp add smoobu \
  --scope user \
  --env SMOOBU_API_KEY=DEIN_KEY \
  -- npx -y @hostautomation/smoobu-mcp

--scope user macht den Server in allen Projekten verfügbar. Danach in Claude Code /mcp eingeben — smoobu sollte als verbunden erscheinen. Version pinnen für reproduzierbare Installs: npx -y @hostautomation/[email protected].

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

{
  "mcpServers": {
    "smoobu": {
      "command": "npx",
      "args": ["-y", "@hostautomation/smoobu-mcp"],
      "env": {
        "SMOOBU_API_KEY": "DEIN_KEY"
      }
    }
  }
}

Variante B – aus dem Quellcode (wenn du Option B aus Schritt 2 genutzt hast): im smoobu-mcp-Ordner -- node "$(pwd)/build/index.js" statt -- npx -y @hostautomation/smoobu-mcp.

Schritt 3b – In Claude Desktop einbinden

Konfigurationsdatei öffnen/anlegen:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Denselben mcpServers-Block wie oben (JSON-Variante aus Schritt 3) eintragen und Claude Desktop neu starten.

Benutzung

Beispiel-Prompts, sobald der Server verbunden ist:

„Welche Apartments habe ich in Smoobu?"
„Zeig mir alle Anreisen zwischen dem 2026-07-01 und 2026-07-07."
„Ist Apartment 12345 vom 2026-08-10 bis 2026-08-14 frei und was kostet es?"
„Hol mir die Buchungsdetails zu Reservierung 906."
„Liste die Nachrichten zur Reservierung 906."

Mit aktiviertem Schreibzugriff zusätzlich:

„Lege eine Buchung in Apartment 12345 vom 2026-09-01 bis 2026-09-03 für Max Mustermann an."
„Setze für Apartment 12345 vom 2026-12-20 bis 2026-12-27 den Tagespreis auf 180 €."

Tool-Referenz

| Tool | Typ | Smoobu-Endpoint | Wichtige Parameter | |---|---|---|---| | smoobu_get_account | read | GET /api/me | – | | smoobu_list_apartments | read | GET /api/apartments | – | | smoobu_get_apartment | read | GET /api/apartments/{id} | apartmentId | | smoobu_list_reservations | read | GET /api/reservations | arrivalFrom/To, departureFrom/To, from/to, modifiedFrom/To, apartmentId, page, pageSize (max 100) | | smoobu_get_reservation | read | GET /api/reservations/{id} | reservationId | | smoobu_get_rates | read | GET /api/rates | apartments[], start_date, end_date | | smoobu_check_availability | read | POST /booking/checkApartmentAvailability | arrivalDate, departureDate, apartments[], customerId (auto) | | smoobu_list_messages | read | GET /api/reservations/{id}/messages | reservationId, page, onlyRelatedToGuest | | smoobu_list_guests | read | GET /api/guests | query, page, pageSize | | smoobu_get_guest | read | GET /api/guests/{id} | guestId | | smoobu_create_reservation | write | POST /api/reservations | arrivalDate, departureDate, apartmentId (Pflicht) + Gast-/Preisfelder | | smoobu_update_reservation | write | PUT /api/reservations/{id} | reservationId + änderbare Felder | | smoobu_cancel_reservation | write | DELETE /api/reservations/{id} | reservationId | | smoobu_update_rates | write | POST /api/rates | apartments[], operations[] | | smoobu_send_guest_message | write | POST /api/reservations/{id}/messages/send-message-to-guest | reservationId, subject, messageBody |

Wichtige Smoobu-Eigenheiten (im Server berücksichtigt):

Alle Datumswerte sind YYYY-MM-DD, Uhrzeiten HH:MM.
smoobu_update_reservation kann nicht An-/Abreisedatum oder Apartment ändern – dafür eine neue Buchung anlegen.
Stornieren = „cancelled" markieren (nicht hart löschen); mit showCancellation=true wieder auffindbar.
channelId beim Anlegen default 70 (Direkt-/API-Buchung).
Rate-Limit: 1000 Requests/Minute (HTTP 429 bei Überschreitung).

Schreibzugriff aktivieren

Schreib-Tools nur einschalten, wenn du sie wirklich brauchst:

claude mcp add smoobu \
  --scope user \
  --env SMOOBU_API_KEY=DEIN_KEY \
  --env SMOOBU_ALLOW_WRITES=true \
  -- npx -y @hostautomation/smoobu-mcp

Empfehlung: Erst mit echten Daten read-only testen, dann Schreibzugriff zunächst auf einem Test-Apartment ausprobieren.

Optional: als HTTP-Server hosten

Statt lokal pro Person kannst du den Server einmal zentral hosten (z. B. für mehrere Franchisenehmer). Der Server-Code ist transport-unabhängig.

Sicherheits-Defaults: Der HTTP-Modus bindet standardmäßig nur an 127.0.0.1 und warnt, wenn kein Auth-Token gesetzt ist – der Endpoint hat vollen Zugriff auf deinen Smoobu-Account.

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

| Variable | Zweck | |---|---| | MCP_HTTP_HOST | Bind-Adresse (Default 127.0.0.1; 0.0.0.0 nur zum externen Freigeben) | | MCP_HTTP_AUTH_TOKEN | Wenn gesetzt, müssen Clients Authorization: Bearer <token> senden | | MCP_HTTP_ALLOWED_HOSTS | Komma-getrennte Host-Allowlist (aktiviert DNS-Rebinding-Schutz) |

Einbinden in Claude Code (mit Token):

claude mcp add --transport http smoobu-remote https://dein-host.example/mcp \
  --header "Authorization: Bearer ein-langes-zufallstoken"

Für öffentliches Hosting immer TLS + Auth-Token setzen und idealerweise einen authentifizierenden Reverse-Proxy davorschalten.

Veröffentlichen auf npm (für Maintainer)

Veröffentlicht wird unter der Organisation @hostautomation (nicht auf einem privaten Profil), als öffentliches Paket @hostautomation/smoobu-mcp.

Einmalig: npm-Organisation hostautomation anlegen (kostenlos für öffentliche Pakete) unter https://www.npmjs.com/org/create und sicherstellen, dass dein npm-Account dort Publish-Recht hat.

Pro Version (Befehle einzeln, ohne Kommentare):

cd smoobu-mcp
npm login
npm test
npm publish

publishConfig.access = public ist in package.json gesetzt – sonst würde ein scoped Paket privat landen. npm pack --dry-run zeigt vorab den Inhalt (nur build/, README, LICENSE, .env.example – kein Quellcode, keine Secrets).

Neue Version: npm version patch|minor|major, danach npm publish.

Das Paket enthält keine Zugangsdaten. Jede:r Nutzer:in gibt den eigenen Smoobu-API-Key per Umgebungsvariable an – es gibt keinen zentralen Datenfluss und kein zentrales Gast-PII. Damit bleibt die DSGVO-Last bei den jeweiligen Nutzer:innen (eigener Verantwortlicher), nicht bei dir als Herausgeber.

DSGVO-Hinweis

Reservierungs- und Gästedaten sind personenbezogene Daten. Wenn Claude diese Tools nutzt, fließen Gastdaten an den KI-Anbieter (Anthropic). Praktisch:

Nutze nur den kommerziellen Claude-Tarif (API/Team/Enterprise) mit Auftragsverarbeitungsvertrag (AVV) – nicht den Consumer-Tarif.
Datenminimierung: gezielte Einzelabfragen statt Massen-Exporte mit voller PII.
Smoobu und Anthropic als Auftragsverarbeiter in dein Verzeichnis von Verarbeitungstätigkeiten aufnehmen.

Mehr dazu im übergeordneten DSGVO-/Compliance-Dokument (die Grundsätze gelten analog für Smoobu).

Fehlerbehebung

| Symptom | Ursache / Lösung | |---|---| | SMOOBU_API_KEY is not set | Env-Variable fehlt in der MCP-Konfiguration. | | Smoobu API 401 … | API-Key falsch/abgelaufen – in Smoobu neu generieren. | | Smoobu API 429 … | Rate-Limit (1000/min) erreicht – kurz warten. | | Schreib-Tools fehlen | SMOOBU_ALLOW_WRITES=true ist nicht gesetzt (gewollt). | | Server taucht in /mcp nicht auf | Pfad zu build/index.js prüfen; npm run build gelaufen? Node ≥ 18? | | Nichts passiert / Logs sehen | Server loggt auf stderr (stdout ist der MCP-Kanal). |

Architektur

src/
├── index.ts          # Einstieg: wählt stdio (default) oder http
├── server.ts         # baut den McpServer, registriert Tools
├── http.ts           # optionaler Streamable-HTTP-Transport (lazy)
├── config.ts         # Env-Parsing, Read-only-Flag
├── smoobu-client.ts  # dünne HTTP-Schicht (Auth, URL, Timeout, Fehler)
└── tools/            # ein Modul je Themenbereich, Writes per Flag gegated
    ├── account.ts  apartments.ts  reservations.ts
    ├── rates.ts    messages.ts    guests.ts
    └── index.ts

Datenquelle der API-Abbildung: docs.smoobu.com (verifiziert Juni 2026).