flexible-hotels-mcp-server

AI（Claude やその他の MCP クライアント）が、固定のチェックイン/チェックアウト日ではなく、柔軟な日付範囲内の宿泊日数に基づいてホテルの部屋を検索できるようにする MCP（Model Context Protocol）サーバーです。

例：「テルアビブで3泊、9月1日から9月20日の間のどこかで」— サーバーは範囲内のすべての可能なチェックイン日をスキャンし、それぞれの実際の価格を取得して、価格順に並べた最もお得な取引を返します。

アフィリエイトモデル: これは価格比較ツールのみです — 支払い情報を収集したり、予約を実行したりすることはありません。各結果には、ユーザーが自分で購入を完了できるソース（現時点では Booking.com）へのリンク（bookingUrl）が含まれています。

データソース: Amadeus for Developers — 観光分野をリードする無料APIで、完全に無料のテスト環境（test）があり、クレジットカードは不要です。

含まれるもの

AIに公開されている4つのツール:

「柔軟な検索」ロジックはsrc/services/hotelSearch.tsに実装されています：Amadeus（および他のすべてのプロバイダー）は呼び出しごとに固定の日付範囲のみをサポートするため、サーバーは定義されたウィンドウ内のすべての可能なチェックイン日を自分でスキャンし、それに応じてAPIを呼び出し、結果を集約します。各結果へのリンクはsrc/services/affiliateLink.tsで構築されます。

Related MCP server: AigoHotel MCP Server

インストール

1. 無料のAPIキーを取得する（2分、クレジットカード不要）:

1. https://developers.amadeus.com/register で登録する

2. 認証後、My Self-Service Workspace で「New App」を作成する

3. API Key と API Secret を受け取る — これらが AMADEUS_CLIENT_ID と AMADEUS_CLIENT_SECRET になります

これはtest（サンドボックス）環境です — 完全に無料で、寛大な月間クォータと毎秒約10リクエストのレート制限があります。世界中の数十万のホテルを実際のデータ（ただし不完全/キャッシュされた場合もあります）でカバーしています。将来、完全なライブデータに切り替えるには、Amadeusにproductionアクセスを申請（有料）し、AMADEUS_ENV=production に変更します。

2. ローカルインストール:

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

3. すべてが機能することを確認する（クォータを消費せず、Amadeusに実際のリクエストを送信しません）:

npm test

実行

npm start

デフォルトでは、サーバーはstdio経由で実行されます（Claude Desktopなどのクライアントへのローカル接続に適しています）。HTTP経由のリモートサーバーとして実行する場合（Claude.ai / Cowork への「カスタムコネクタ」として、または他のリモートMCPクライアントからの接続用）:

TRANSPORT=http PORT=3000 npm start

AIへの「プラグイン」としての接続

Claude Desktop（ローカル）

設定ファイル claude_desktop_config.json に追加します:

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

Claude Desktopを再起動すると、AIは会話内でこれらのツールを直接呼び出せるようになります。

リモート接続（Claude.ai / Cowork / その他のクライアント）

製品を複数のユーザーがローカルでコードを実行せずに「プラグイン」として利用できるようにするには、サーバーをTRANSPORT=httpモードでサーバー/ホストにデプロイし、クライアント設定で https://あなたのドメイン/mcp アドレスをカスタムMCPコネクタとして接続します。

Railway（すでにアカウント + CLIがインストールされている場合に推奨）:

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

サーバーは、Amadeusキーを設定する前でも起動し（ヘルスチェックに合格します）— 実際のキーが設定されて自動再デプロイが行われるまで、検索ツールは明確なエラーを返すだけです。

Render: プロジェクトルートのrender.yamlファイルがBlueprintとして準備されています — repoをRenderに接続し、「New」→「Blueprint」で、インターフェースでAMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRETを入力します（ファイル内のコメントを参照）。

すべてのオプションで注意：AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRETはホストサーバー上の環境変数として設定する必要があり、コードに記述してはいけません。

使用例（AIが「見る」もの）

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

ビジネスモデル: アフィリエイト

このサーバーは予約を実行せず、いかなる段階でも支払い情報に触れません — これは意図的で、シンプルさ/安全性のためであり、また「外部チェックアウト」を要求し、ツール自体によるクレジットカード番号の収集を禁止するアプリストア（ChatGPT App Directoryなど）の仕組みに沿ったものです。

実際の仕組み:

1. サーバーはAmadeus（無料）を通じて実際の価格を検索します。

2. 各結果について、ホテル名と日付が事前入力されたBooking.comの検索ページへのリンクが構築されます（src/services/affiliateLink.ts）。

3. Booking.com Affiliate Partner Program（無料、自己登録、特別な承認不要）に登録してaidを取得すると、環境変数BOOKING_AFFILIATE_IDとして設定できます — するとすべてのリンクにあなたのパートナーIDが含まれ、リンク経由で行われた予約に対してコミッションを受け取れます。

4. BOOKING_AFFILIATE_IDがなくてもリンクは完全に機能します — ただ報酬が発生しないだけです。

これはまさにあなたが求めた「登録するだけ」です：Booking.comのパートナープログラムへの一度きりの登録（AmadeusやRailwayではなく）だけで、リンクが収益を生み始めます。

既知の制限事項

• 無料クォータ: Amadeusのtest環境は月間クォータとリクエストレート（約10/秒）に制限があります。N日間のウィンドウでの柔軟な検索は最大N回のリクエストを送信します（間に軽い遅延あり）— ウィンドウが大きいほど検索が遅くなります。クォータを保護するため、ウィンドウは検索ごとに30日に制限されています。

• ホテル数: デフォルトでは、各日付について都市内の最大15のホテルがチェックされます（max_hotelsで最大30まで増やせるか、特定のhotelIdsに絞り込めます）。

• サンドボックスデータ: test環境では、カバレッジが最も信頼できるのは大都市（例：NYC、LON、PAR）です。小さな都市ではホテルが少ないかゼロの場合があります — これはproductionへの移行で解決されます。

• 予約リンクはホテル名と日付に基づいてBooking.comの検索を構築します — Amadeusが提供しないため、特定の部屋へのディープリンクではありません。ほとんどの場合、関連するホテルが結果の最初に表示されます。

プロジェクト構造

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

今後の拡張の可能性

• 固定数ではなく柔軟な宿泊日数範囲（最小/最大泊数）。

• クォータ節約のための検索結果のキャッシュ。

• 追加のアフィリエイトプログラム（Expedia、Agodaなど）への参加と、Booking.comだけでなく各結果に複数のソースへのリンクを表示。

• 製品が成長するにつれて、より広いプロバイダーカバレッジのための有料プロバイダー（StayAPI / RapidAPIなど）への移行。

• ChatGPTアプリストア（Apps SDK）への登録 — 独自の要件（OpenAI開発者アカウント、プライバシーポリシー、テスト用デモアカウント）を持つ別プロジェクト。現在のアフィリエイトモデル（クレジットカード収集なし）は、すでに彼らの「外部チェックアウト」要件に準拠しています。