flexible-hotels-mcp-server

Servidor MCP (Model Context Protocol) que permite a la IA (Claude o cualquier otro cliente MCP) buscar habitaciones de hotel por número de noches en un rango de fechas flexible, en lugar de por una fecha fija de check-in/check-out.

Por ejemplo: "3 noches en Tel Aviv, en algún momento entre el 1.9 y el 20.9" — el servidor escanea todas las fechas de check-in posibles dentro del rango, obtiene precios reales para cada una y devuelve las ofertas más baratas ordenadas por precio.

Modelo de afiliado: es una herramienta de comparación de precios únicamente — no recopila datos de pago ni realiza reservas. Cada resultado incluye un enlace (bookingUrl) que dirige a la fuente (actualmente Booking.com) donde el usuario puede completar la compra por sí mismo, si así lo desea.

Fuente de datos: Amadeus for Developers — la API gratuita líder en el sector turístico, con un entorno de pruebas (test) totalmente gratuito y sin necesidad de tarjeta de crédito.

Qué hay aquí

Cuatro herramientas (tools) expuestas a la IA:

La lógica de "búsqueda flexible" está implementada en src/services/hotelSearch.ts: dado que Amadeus (y cualquier otro proveedor) solo admite un rango de fechas fijo por llamada, el servidor escanea por sí mismo cada fecha de check-in posible dentro de la ventana definida, llama a la API en consecuencia y agrega los resultados. El enlace de cada resultado se construye en src/services/affiliateLink.ts.

Related MCP server: AigoHotel MCP Server

Instalación

1. Obtén una clave de API gratuita (2 minutos, sin tarjeta de crédito):

1. Regístrate en https://developers.amadeus.com/register

2. Después de la verificación, crea una "New App" en My Self-Service Workspace

3. Recibirás un API Key y un API Secret — estos serán AMADEUS_CLIENT_ID y AMADEUS_CLIENT_SECRET

Este es el entorno de test (sandbox) — totalmente gratuito, con una cuota mensual generosa y un límite de velocidad de unas 10 solicitudes por segundo. Cubre cientos de miles de hoteles en todo el mundo con datos reales (aunque a veces parciales/en caché). Para pasar a datos en vivo completos en el futuro, se puede solicitar acceso de producción a Amadeus (de pago) y cambiar AMADEUS_ENV=production.

2. Instalación local:

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

3. Comprobar que todo funciona (sin afectar a la cuota — no envía solicitudes reales a Amadeus):

npm test

Ejecución

npm start

Por defecto, el servidor se ejecuta a través de stdio (adecuado para conexión local con clientes como Claude Desktop). Para ejecutarlo como servidor remoto por HTTP (para conectar desde Claude.ai / Cowork como "custom connector", o desde cualquier otro cliente MCP remoto):

TRANSPORT=http PORT=3000 npm start

Conexión como "plugin" a la IA

Claude Desktop (local)

Añade al archivo de configuración claude_desktop_config.json:

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

Tras reiniciar Claude Desktop, la IA podrá llamar a estas herramientas directamente en la conversación.

Conexión remota (Claude.ai / Cowork / cualquier otro cliente)

Para que el producto esté disponible como "plugin" para varios usuarios sin que cada uno ejecute código localmente, hay que desplegar (deploy) el servidor en modo TRANSPORT=http en algún servidor/host, y luego conectar la dirección https://su-dominio/mcp como conector MCP personalizado en la configuración del cliente.

Railway (recomendado si ya tienes cuenta + CLI instalado):

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

El servidor se levanta (y pasa el health check) incluso antes de configurar las claves de Amadeus — las herramientas de búsqueda simplemente devolverán un error claro hasta que se configuren las claves reales y se haga un nuevo despliegue automático.

Render: el archivo render.yaml en la raíz del proyecto está listo como Blueprint — conecta el repo a Render, "New" -> "Blueprint", y rellena AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET en la interfaz (ver comentarios dentro del archivo).

Ten en cuenta en todas las opciones: AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET deben ser variables de entorno definidas en el servidor de alojamiento, nunca escritas en el código.

Ejemplo de uso (lo que "ve" la IA)

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

El modelo de negocio: afiliado

Este servidor no realiza reservas ni toca datos de pago en ninguna fase — es intencional, tanto por simplicidad/seguridad como porque así funcionan las tiendas de aplicaciones (como ChatGPT App Directory) que exigen "external checkout" y prohíben recopilar números de tarjeta de crédito a través de la propia herramienta.

Cómo funciona en la práctica:

1. El servidor encuentra precios reales a través de Amadeus (gratis).

2. Para cada resultado se construye un enlace a la página de búsqueda de Booking.com con el nombre del hotel y las fechas ya rellenados (src/services/affiliateLink.ts).

3. Si te registras en el Booking.com Affiliate Partner Program (gratuito, registro independiente, sin aprobación especial) y obtienes un aid, puedes configurarlo como variable de entorno BOOKING_AFFILIATE_ID — entonces cada enlace incluirá tu identificador de socio y podrás recibir comisiones por las reservas realizadas a través del enlace.

4. Sin BOOKING_AFFILIATE_ID los enlaces siguen funcionando perfectamente — simplemente no generan comisión.

Esto es exactamente el "solo hay que registrarse" que pediste: el registro único en el programa de socios de Booking.com (no en Amadeus, no en Railway) es todo lo que se necesita para que los enlaces empiecen a generar ingresos.

Limitaciones conocidas

• Cuota gratuita: el entorno de test de Amadeus está limitado en cuota mensual y en velocidad de solicitudes (~10/segundo). Una búsqueda flexible sobre una ventana de N días envía hasta N solicitudes (con una ligera pausa entre ellas) — ventana grande = búsqueda más lenta. La ventana está limitada a 30 días por búsqueda para proteger la cuota.

• Número de hoteles: por defecto se comprueban hasta 15 hoteles en la ciudad por fecha (se puede aumentar hasta 30 mediante max_hotels, o reducir a hotelIds específicos).

• Datos de sandbox: en el entorno de test, la cobertura más fiable está en las grandes ciudades (por ejemplo, NYC, LON, PAR). Las ciudades más pequeñas pueden devolver pocos hoteles o ninguno — esto se resuelve al pasar a production.

• Los enlaces de reserva construyen una búsqueda en Booking.com por nombre de hotel y fechas — no un enlace profundo (deep link) directo a la habitación específica, porque Amadeus no lo proporciona. En la mayoría de los casos, el hotel relevante aparecerá primero en los resultados.

Estructura del proyecto

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

Posibles ampliaciones futuras

• Rango de noches flexible (min/max nights) y no solo un número fijo.

• Caché de resultados de búsqueda para ahorrar cuota.

• Incorporación de programas de afiliados adicionales (Expedia, Agoda, etc.) y mostrar varios enlaces a diferentes fuentes por cada resultado, no solo Booking.com.

• Migración a un proveedor de pago (como StayAPI / RapidAPI) para una cobertura más amplia de proveedores cuando el producto crezca.

• Registro en la tienda de aplicaciones de ChatGPT (Apps SDK) — proyecto aparte con sus propios requisitos (cuenta de desarrollador en OpenAI, política de privacidad, cuenta demo para pruebas); el modelo de afiliado actual (sin recopilación de tarjetas de crédito) ya cumple con su requisito de "external checkout".