flexible-hotels-mcp-server

Ein MCP-Server (Model Context Protocol), der es einer KI (Claude oder einem anderen MCP-Client) ermöglicht, Hotelzimmer nach Anzahl der Nächte in einem flexiblen Datumsbereich zu suchen, anstatt nach einem festen Check-in-/Check-out-Datum.

Zum Beispiel: „3 Nächte in Tel Aviv, irgendwann zwischen dem 1.9. und dem 20.9." – der Server durchsucht alle möglichen Check-in-Daten im Bereich, holt echte Preise für jedes davon und liefert die günstigsten Angebote, sortiert nach Preis.

Affiliate-Modell: Dies ist ein reines Preisvergleichstool – es sammelt keine Zahlungsdaten und führt keine Buchung durch. Jedes Ergebnis enthält einen Link (bookingUrl), der zur Quelle (derzeit Booking.com) führt, wo der Nutzer den Kauf selbst abschließen kann, falls er das überhaupt möchte.

Datenquelle: Amadeus for Developers – die führende kostenlose API im Tourismusbereich, mit einer komplett kostenlosen Testumgebung (test) und ohne Kreditkartenpflicht.

Was es hier gibt

Vier Tools, die der KI zur Verfügung stehen:

Die Logik der „flexiblen Suche" ist in src/services/hotelSearch.ts umgesetzt: Da Amadeus (und jeder andere Anbieter) nur einen festen Datumsbereich pro Aufruf unterstützt, durchsucht der Server selbst jedes mögliche Check-in-Datum im definierten Fenster, ruft die API entsprechend auf und bündelt die Ergebnisse. Der Link für jedes Ergebnis wird in src/services/affiliateLink.ts erstellt.

Related MCP server: AigoHotel MCP Server

Installation

1. Kostenlosen API-Schlüssel erhalten (2 Minuten, ohne Kreditkarte):

1. Registrieren Sie sich unter https://developers.amadeus.com/register

2. Erstellen Sie nach der Verifizierung eine „New App" in My Self-Service Workspace

3. Sie erhalten einen API Key und ein API Secret – diese werden zu AMADEUS_CLIENT_ID und AMADEUS_CLIENT_SECRET

Dies ist die test-Umgebung (Sandbox) – komplett kostenlos, mit großzügigem Monatskontingent und einem Ratenlimit von etwa 10 Anfragen pro Sekunde. Sie deckt Hunderttausende Hotels weltweit mit echten Daten ab (wenn auch manchmal teilweise/gecacht). Um später auf vollständige Live-Daten umzusteigen, können Sie bei Amadeus Produktionszugriff (kostenpflichtig) beantragen und AMADEUS_ENV=production setzen.

2. Lokale Installation:

npm install
cp .env.example .env
# ערכו את .env והכניסו את המפתחות שקיבלתם
npm run build

3. Prüfen, dass alles funktioniert (ohne das Kontingent zu belasten – sendet keine echten Anfragen an Amadeus):

npm test

Ausführung

npm start

Standardmäßig läuft der Server über stdio (geeignet für die lokale Verbindung mit Clients wie Claude Desktop). Um ihn als entfernten HTTP-Server auszuführen (für die Verbindung von Claude.ai / Cowork als „custom connector" oder von jedem anderen entfernten MCP-Client):

TRANSPORT=http PORT=3000 npm start

Verbindung als „Plugin" mit der KI

Claude Desktop (lokal)

Fügen Sie zur Konfigurationsdatei claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "flexible-hotels": {
      "command": "node",
      "args": ["/נתיב-מלא/ל/flexible-hotels-mcp-server/dist/index.js"],
      "env": {
        "AMADEUS_CLIENT_ID": "המפתח-שלכם",
        "AMADEUS_CLIENT_SECRET": "הסוד-שלכם"
      }
    }
  }
}

Nach einem Neustart von Claude Desktop kann die KI diese Tools direkt im Gespräch aufrufen.

Entfernte Verbindung (Claude.ai / Cowork / jeder andere Client)

Damit das Produkt als „Plugin" für mehrere Benutzer verfügbar ist, ohne dass jeder lokal Code ausführen muss, muss der Server im Modus TRANSPORT=http auf einem Server/Host bereitgestellt (deployt) werden. Anschließend verbinden Sie die Adresse https://ihre-domain/mcp als Custom-MCP-Connector in den Client-Einstellungen.

Railway (empfohlen, wenn Sie bereits ein Konto + CLI installiert haben):

cd flexible-hotels-mcp-server
railway login          # רק אם עוד לא מחוברים — פותח דפדפן לאישור
railway up --new -y --detach --json   # יוצר פרויקט חדש, מעלה את הקוד ומפעיל build מה-Dockerfile
railway variable set AMADEUS_CLIENT_ID=המפתח-שלכם --skip-deploys
railway variable set AMADEUS_CLIENT_SECRET=הסוד-שלכם --skip-deploys
railway variable set AMADEUS_ENV=test
railway domain          # מפיק כתובת ציבורית כמו https://xxx.up.railway.app

Der Server startet (und besteht den Health Check) auch bevor die Amadeus-Schlüssel konfiguriert sind – die Suchtools geben dann einfach eine klare Fehlermeldung zurück, bis die echten Schlüssel gesetzt und ein automatisches Re-Deployment erfolgt ist.

Render: Die Datei render.yaml im Projektstamm ist als Blueprint vorbereitet – verbinden Sie das Repo mit Render, „New" -> „Blueprint", und füllen Sie AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET in der Oberfläche aus (siehe Kommentare in der Datei).

Beachten Sie bei allen Optionen: AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET müssen als Umgebungsvariablen auf dem Host-Server definiert sein, niemals im Code.

Beispielverwendung (was die KI „sieht")

User: תמצא לי 3 לילות בתל אביב, איפשהו בין ה-1 ל-20 בספטמבר, לזוג.

AI calls: flexible_hotels_resolve_city_code(keyword="Tel Aviv")
  -> TLV

AI calls: flexible_hotels_search_flexible_offers(
  city_code="TLV", nights=3,
  earliest_check_in="2026-09-01", latest_check_in="2026-09-20",
  adults=2
)
  -> רשימת עסקאות ממוינת מהזולה ביותר, עם תאריך צ'ק-אין/אאוט מדויק וקישור הזמנה לכל אחת

User: מעולה, תראה לי את הפרטים המלאים של האופציה הכי זולה.

AI calls: flexible_hotels_get_offer_details(offer_id="...")
  -> מחיר מעודכן + קישור לחיצה שמעביר את המשתמש להשלים את ההזמנה באתר המקורי

Das Geschäftsmodell: Affiliate

Dieser Server führt keine Buchungen durch und berührt in keiner Phase Zahlungsdaten – das ist beabsichtigt, sowohl aus Gründen der Einfachheit/Sicherheit als auch, weil App-Stores (wie das ChatGPT App Directory) so funktionieren: Sie verlangen einen „external checkout" und verbieten das Sammeln von Kreditkartennummern über das Tool selbst.

So funktioniert es in der Praxis:

1. Der Server findet echte Preise über Amadeus (kostenlos).

2. Für jedes Ergebnis wird ein Link zur Suchseite auf Booking.com erstellt, bei dem Hotelname und Daten bereits ausgefüllt sind (src/services/affiliateLink.ts).

3. Wenn Sie sich beim Booking.com Affiliate Partner Program anmelden (kostenlos, eigenständige Registrierung, ohne besondere Genehmigung) und eine aid erhalten, können Sie diese als Umgebungsvariable BOOKING_AFFILIATE_ID festlegen – dann enthält jeder Link Ihre Partner-ID und Sie können Provisionen für Buchungen erhalten, die über den Link erfolgen.

4. Ohne BOOKING_AFFILIATE_ID funktionieren die Links weiterhin vollständig – sie sind nur nicht vergütet.

Das ist genau das „nur registrieren", das Sie wollten: Eine einmalige Anmeldung beim Partnerprogramm von Booking.com (nicht bei Amadeus, nicht bei Railway) ist alles, was nötig ist, damit die Links anfangen, Einnahmen zu generieren.

Bekannte Einschränkungen

• Kostenloses Kontingent: Die test-Umgebung von Amadeus ist durch ein Monatskontingent und eine Anfragenrate (~10/Sekunde) begrenzt. Eine flexible Suche über ein Fenster von N Tagen sendet bis zu N Anfragen (mit einer leichten Verzögerung dazwischen) – ein großes Fenster bedeutet eine langsamere Suche. Das Fenster ist auf 30 Tage pro Suche begrenzt, um das Kontingent zu schützen.

• Anzahl der Hotels: Standardmäßig werden bis zu 15 Hotels in der Stadt pro Datum geprüft (über max_hotels auf bis zu 30 erhöhbar, oder auf bestimmte hotelIds eingrenzbar).

• Sandbox-Daten: In der test-Umgebung ist die Abdeckung in großen Städten am zuverlässigsten (z. B. NYC, LON, PAR). Kleinere Städte können wenige oder keine Hotels zurückgeben – das wird durch den Wechsel zu production behoben.

• Die Buchungslinks erstellen eine Suche auf Booking.com nach Hotelname und Daten – kein direkter Deep Link zum spezifischen Zimmer, da Amadeus keinen solchen bereitstellt. In den meisten Fällen erscheint das relevante Hotel zuerst in den Ergebnissen.

Projektstruktur

src/
├── index.ts              # נקודת כניסה, רישום השרת והכלים
├── constants.ts           # קבועים (URLs, מגבלות)
├── types.ts                # טיפוסי TypeScript משותפים
├── services/
│   ├── amadeusClient.ts   # קליינט HTTP מאומת ל-Amadeus (OAuth2, endpoints)
│   ├── hotelSearch.ts     # הלוגיקה של חיפוש גמיש (הליבה)
│   ├── affiliateLink.ts   # בניית קישור ההזמנה (Booking.com + aid אופציונלי)
│   └── format.ts           # פורמט markdown לתשובות
├── schemas/
│   └── schemas.ts          # סכמות Zod לכל כלי
├── tools/                  # רישום כל כלי MCP
└── test/
    └── hotelSearch.test.ts # בדיקות יחידה ללוגיקת החיפוש (ללא צורך במפתח API)
scripts/
└── smoke-test-tools.mjs    # בדיקת עשן שמפעילה את השרת האמיתי ומוודאת שכל הכלים נחשפים כראוי

Mögliche zukünftige Erweiterungen

• Flexibler Nächtebereich (min/max Nächte) statt nur einer festen Anzahl.

• Caching von Suchergebnissen zur Schonung des Kontingents.

• Beitritt zu weiteren Affiliate-Programmen (Expedia, Agoda usw.) und Anzeige mehrerer Links zu verschiedenen Quellen für jedes Ergebnis, nicht nur Booking.com.

• Wechsel zu einem kostenpflichtigen Anbieter (wie StayAPI / RapidAPI) für eine breitere Anbieterabdeckung, wenn das Produkt wächst.

• Registrierung im ChatGPT App Store (Apps SDK) – ein separates Projekt mit eigenen Anforderungen (OpenAI-Entwicklerkonto, Datenschutzrichtlinie, Demo-Konto zum Testen); das aktuelle Affiliate-Modell (ohne Kreditkartenerfassung) entspricht bereits deren „external checkout"-Anforderung.