Skip to main content
Glama

hotel-mcp

Un sistema de reservas de hotel muy sencillo con dos formas de usarlo:

  • Una web de recepción para el personal del hotel.

  • Un servidor MCP para que un asistente de IA (Claude Desktop, Claude Code, Cursor…) pueda consultar disponibilidad, hacer reservas y cancelarlas hablando con él.

Los dos usan la misma base de datos, así que si le pides a Claude que reserve una habitación, la reserva aparece en la web a los pocos segundos (en morado).

Lo hice para practicar MCP con el SDK oficial de Python, y lo he dejado pequeño a propósito.

Qué es MCP, en una frase

MCP (Model Context Protocol) es un estándar para conectar asistentes de IA con sistemas externos. Tú escribes un "servidor MCP" que expone unas funciones, y cualquier asistente compatible puede usarlas sin integraciones a medida.

Related MCP server: 1Stay Hotel Booking

Cómo funciona

   Claude (Desktop / Code)              Navegador
          │                                 │
          │ MCP                             │ HTTP
          ▼                                 ▼
   hotel/mcp_server.py               hotel/web.py + static/index.html
   (lo que puede hacer la IA)        (la web de recepción)
          └────────────────┬────────────────┘
                           ▼
                     hotel/core.py   ← las reglas del hotel
                           ▼
                        hotel.db     ← base de datos SQLite
  1. core.py contiene toda la lógica: qué habitaciones están libres, cuánto cuesta una estancia, cómo se reserva, cómo se cancela y cuánto se devuelve. Guarda los datos en SQLite. La primera vez crea la base de datos con 6 habitaciones y unas reservas de ejemplo.

  2. mcp_server.py es el servidor MCP. Son unas pocas funciones que llaman a core.py. Cada función lleva el decorador @mcp.tool(), y con eso el SDK ya las publica para que Claude las vea y las use.

  3. web.py es la web de recepción, hecha con FastAPI. También llama a core.py.

Como el MCP y la web usan la misma lógica y la misma base de datos, siempre están sincronizados.

Qué puede hacer la IA

Tipo

Nombre

Qué hace

tool

check_availability

Habitaciones libres para unas fechas y número de personas, con el precio. También dice qué día es hoy

tool

get_booking

Muestra una reserva a partir de su localizador (por ejemplo ABC123)

tool

occupancy_report

Quién está alojado, quién llega y quién se va un día concreto

tool

create_booking

Hace una reserva (pide confirmación antes)

tool

cancel_booking

Cancela una reserva (pide confirmación antes)

resource

hotel://policies

Las normas de cancelación del hotel

prompt

front_desk_briefing

Plantilla para pedir el resumen del día en recepción

  • Las tools son acciones que la IA decide usar.

  • Los resources son información que se puede leer.

  • Los prompts son plantillas que elige el usuario.

Ejemplo de conversación

Tú:      ¿Hay una doble libre el fin de semana que viene?
Claude:  (usa check_availability)
         Sí, la 202, de viernes a domingo, 220 €. ¿La reservo?
Tú:      Sí, a nombre de Eva Ruiz, eva@example.com.
Claude:  (usa create_booking sin confirmar → le devuelve la pregunta con el precio)
         (usa create_booking con confirm=true)
         Hecho: localizador K7Q2MZ, habitación 202, 220 €.

Ejemplo orientativo: las palabras exactas dependen del asistente.

Decisiones sencillas pero importantes

  • Quien confirma es el usuario, no la IA. Reservar y cancelar se hace en dos pasos. La primera llamada solo devuelve la pregunta con el precio o el reembolso. La reserva o cancelación solo se ejecuta si la IA vuelve a llamar con confirm=true, y la descripción de la tool le indica que lo haga únicamente cuando el usuario diga que sí.

  • No se puede reservar dos veces la misma habitación. La comprobación de disponibilidad y la reserva van dentro de una misma transacción, así que aunque la web y la IA reserven a la vez, solo una lo consigue.

  • Errores claros. Si algo no se puede hacer, el mensaje explica qué pasa y qué hacer ("La habitación 102 no está libre… usa check_availability"). La IA lo lee y se corrige sola.

  • La IA sabe qué día es. Un modelo no sabe la fecha de hoy, así que check_availability se la devuelve. Así entiende bien "el fin de semana que viene".

Cómo arrancarlo

Necesitas Python 3.10 o superior.

git clone https://github.com/ianfloresfdez/hotel-mcp
cd hotel-mcp
python -m venv .venv
.venv\Scripts\activate          # en Windows  (en macOS/Linux: source .venv/bin/activate)
pip install -e ".[dev]"

Web de recepción: ejecuta hotel-web y abre http://127.0.0.1:8850

Conectarlo a Claude Desktop: en Claude Desktop ve a Settings → Developer → Edit Config, añade esto y reinicia Claude:

{
  "mcpServers": {
    "hotel": {
      "command": "C:/ruta/a/hotel-mcp/.venv/Scripts/hotel-mcp.exe"
    }
  }
}

En macOS/Linux la ruta es /ruta/a/hotel-mcp/.venv/bin/hotel-mcp.

No hace falta arrancar el servidor MCP a mano: Claude lo lanza solo cuando lo necesita.

Conectarlo a Claude Code:

claude mcp add hotel -- C:/ruta/a/hotel-mcp/.venv/Scripts/hotel-mcp.exe

Probarlo sin Claude (con el MCP Inspector, una herramienta oficial para llamar a cada tool a mano):

npx @modelcontextprotocol/inspector .venv/Scripts/hotel-mcp.exe

Consejo: deja la web abierta mientras hablas con Claude y verás aparecer sus reservas.

Tests

pytest

Hay 19 tests. Unos prueban las reglas del hotel (solapamiento de fechas, capacidad, cancelaciones…). Otros hablan con el servidor MCP como lo haría Claude.

Qué añadiría para usarlo de verdad

Es un proyecto de práctica. Para producción añadiría:

  • Confirmación con elicitation: que el propio cliente muestre un botón de "Confirmar", en vez de depender de que la IA pregunte.

  • Autenticación (OAuth 2.1) si se usa en remoto, y que cada cliente solo pueda ver sus propias reservas.

  • Una base de datos como PostgreSQL, límites de uso y registro de cada acción de la IA.

Licencia

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with Hostaway's property management platform through standardized MCP tools. Provides access to listings, bookings, guest communication, and availability checking for vacation rental management.
      -
    • F
      license
      A
      quality
      C
      maintenance
      Hotel booking MCP server — the first transaction-complete hotel booking integration for AI agents. Search 300K+ properties in 140+ countries, get live rates and room details, and generate secure checkout URLs. No payment in the AI conversation — guests complete booking at a hosted checkout page and receive a real hotel confirmation number. Set your own booking fee via Stripe Connect.
      8
      30 npm
      3
      -