flexible-hotels-mcp-server

An MCP (Model Context Protocol) server that lets an AI (Claude or any other MCP client) search for hotel rooms by number of nights within a flexible date range, instead of by a fixed check-in/check-out date.

For example: "3 nights in Tel Aviv, sometime between Sep 1 and Sep 20" — the server scans all possible check-in dates in the range, fetches real prices for each one, and returns the cheapest deals sorted by price.

Affiliate model: this is a price-comparison tool only — it does not collect payment details and does not make a booking. Every result includes a link (bookingUrl) that points to the source (currently Booking.com) where the user can complete the purchase themselves, if they so choose.

Data source: Amadeus for Developers — the leading free API in the travel industry, with a completely free test environment and no credit card required.

What's here

Four tools exposed to the AI:

The "flexible search" logic is implemented in src/services/hotelSearch.ts: since Amadeus (and any other provider) supports only one fixed date range per call, the server itself scans every possible check-in date in the defined window, calls the API accordingly, and aggregates the results. The link for each result is built in src/services/affiliateLink.ts.

Related MCP server: AigoHotel MCP Server

Installation

1. Get a free API key (2 minutes, no credit card):

1. Register at https://developers.amadeus.com/register

2. After verification, create a "New App" in My Self-Service Workspace

3. You'll receive an API Key and an API Secret — these will be AMADEUS_CLIENT_ID and AMADEUS_CLIENT_SECRET

This is the test (sandbox) environment — completely free, with a generous monthly quota and a rate limit of about 10 requests per second. It covers hundreds of thousands of hotels worldwide with real data (though sometimes partial/cached). To move to full live data in the future, you can request production access from Amadeus (paid) and change AMADEUS_ENV=production.

2. Local installation:

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

3. Verify everything works (without hitting the quota — sends no real requests to Amadeus):

npm test

Running

npm start

By default the server runs over stdio (suitable for local connection to clients like Claude Desktop). To run as a remote HTTP server (for connecting from Claude.ai / Cowork as a "custom connector", or from any other remote MCP client):

TRANSPORT=http PORT=3000 npm start

Connecting as an AI "plugin"

Claude Desktop (local)

Add to the claude_desktop_config.json configuration file:

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

After restarting Claude Desktop, the AI will be able to call these tools directly in the conversation.

Remote connection (Claude.ai / Cowork / any other client)

To make the product available as a "plugin" to multiple users without each one running code locally, deploy the server in TRANSPORT=http mode on some server/host, then connect the address https://your-domain/mcp as a custom MCP connector in the client settings.

Railway (recommended if you already have an account + CLI installed):

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

The server comes up (and passes the health check) even before the Amadeus keys are configured — the search tools will simply return a clear error until the real keys are set and an automatic redeploy happens.

Render: a render.yaml file in the project root is ready as a Blueprint — connect the repo to Render, "New" -> "Blueprint", and fill in AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET in the UI (see comments inside the file).

Note for all options: AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET must be environment variables defined on the hosting server, never written in code.

Usage example (what the AI "sees")

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="...")
  -> מחיר מעודכן + קישור לחיצה שמעביר את המשתמש להשלים את ההזמנה באתר המקורי

The business model: affiliate

This server does not make bookings and does not touch payment details at any stage — this is intentional, both for simplicity/safety reasons and because that's how app stores (like the ChatGPT App Directory) work, which require "external checkout" and prohibit collecting credit card numbers through the tool itself.

How it works in practice:

1. The server finds real prices through Amadeus (free).

2. For each result, a link to a Booking.com search page is built with the hotel name and dates already filled in (src/services/affiliateLink.ts).

3. If you sign up for the Booking.com Affiliate Partner Program (free, self-registration, no special approval) and receive an aid, you can set it as the BOOKING_AFFILIATE_ID environment variable — then every link will include your partner ID and you can earn a commission on bookings made through the link.

4. Without BOOKING_AFFILIATE_ID the links still work fully — they're just not compensated.

This is exactly the "just need to sign up" you asked for: a one-time registration to the Booking.com partner program (not to Amadeus, not to Railway) is all that's needed for the links to start earning.

Known limitations

• Free quota: Amadeus's test environment is limited by a monthly quota and request rate (~10/sec). A flexible search over a window of N days sends up to N requests (with a slight delay between them) — a large window = a slower search. The window is capped at 30 days per search to protect the quota.

• Number of hotels: by default up to 15 hotels in the city are checked per date (can be raised to 30 via max_hotels, or narrowed down to specific hotelIds).

• Sandbox data: in the test environment the most reliable coverage is in large cities (e.g. NYC, LON, PAR). Smaller cities may return few hotels or none — this is resolved by switching to production.

• Booking links build a Booking.com search by hotel name and dates — not a direct deep link to the specific room, because Amadeus doesn't provide one. In most cases the relevant hotel will appear first in the results.

Project structure

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    # בדיקת עשן שמפעילה את השרת האמיתי ומוודאת שכל הכלים נחשפים כראוי

Possible future extensions

• Flexible night range (min/max nights) rather than just a fixed number.

• Caching of search results to save quota.

• Joining additional affiliate programs (Expedia, Agoda, etc.) and showing multiple links to different sources per result, not just Booking.com.

• Moving to a paid provider (like StayAPI / RapidAPI) for broader provider coverage as the product grows.

• Listing in the ChatGPT app store (Apps SDK) — a separate project with its own requirements (OpenAI developer account, privacy policy, demo account for testing); the current affiliate model (without credit card collection) already complies with their "external checkout" requirement.