HotelPlanet MCP Server

A Model Context Protocol (MCP) server that provides hotel booking tools including search, price checking, booking, and cancellation capabilities using the HotelPlanet API.

Features

The server exposes four main tools:

1. search_hotel_availability - Search for available hotels by property IDs
2. check_price - Get detailed pricing for specific rates
3. book_hotel - Make a hotel reservation
4. cancel_booking - Cancel an existing booking

Setup

1. Install Dependencies

npm install

2. Environment Configuration

Copy the example environment file and configure your API credentials:

cp env.example .env

Edit the .env file with your HotelPlanet API credentials:

# HotelPlanet API Configuration
HOTEL_API_BASE_URL=https://thehotelplanet.com/cm
HOTEL_API_KEY=your_actual_api_key_here

3. Build the Project

npm run build

4. Run the Server

For MCP (AI Agents)

npm start

For n8n (HTTP API)

npm run start:n8n

n8n Integration

This server can be used with n8n workflows via HTTP requests. The n8n version runs on port 3000 by default and provides REST API endpoints.

Available Endpoints

• Health Check: GET http://localhost:3000/health
• API Documentation: GET http://localhost:3000/api/docs
• Search Availability: POST http://localhost:3000/api/search-availability
• Check Price: POST http://localhost:3000/api/check-price
• Book Hotel: POST http://localhost:3000/api/book-hotel
• Cancel Booking: POST http://localhost:3000/api/cancel-booking

n8n Workflow Setup

1. Start the server:

   npm run start:n8n

2. In n8n, add HTTP Request nodes for each operation:

   • Set Method to POST
   • Set URL to the appropriate endpoint
   • Set Headers: Content-Type: application/json
   • Set Body to the JSON payload (see examples below)

3. Test the connection:

   node test-n8n-server.js

n8n Response Format

All endpoints return responses in this format:

{
  "success": true,
  "data": { /* actual response data */ },
  "summary": { /* summary information */ },
  "metadata": {
    "timestamp": "2024-01-01T00:00:00.000Z",
    "request_id": "req_1234567890_abc123"
  }
}

API Endpoints

The server integrates with the following HotelPlanet API endpoints:

• Search Availability: POST /engine/availability
• Check Price: POST /v2/engine/v1/prebook
• Book Hotel: POST /v2/engine/v1/bookv2
• Cancel Booking: POST /engine/cancel

Tool Usage Examples

Search Hotel Availability

{
  "property_ids": [24517],
  "checkin": "2025-11-25",
  "checkout": "2025-11-26",
  "occupancies": [
    {
      "occupancy_index": 0,
      "adults": 2
    }
  ],
  "currency": "EUR",
  "agency": "1745",
  "max_properties": 3,
  "max_rates_per_property": 2,
  "price_range": {
    "min": 100,
    "max": 500
  },
  "star_rating": [4, 5],
  "board_types": ["Breakfast"]
}

💡 Best Practices for AI Agents:

• Limit property_ids to 5-10 properties for best performance
• Use max_properties (default: 5, max: 10) to control response size
• Use max_rates_per_property (default: 3, max: 5) to limit rates shown
• Apply filters (price_range, star_rating, board_types) to get targeted results
• The response includes guidance for next steps (price checking, booking)

Check Price

{
  "availability_request": {
    "property_id": 23755,
    "checkin": "2025-01-13",
    "checkout": "2025-01-14",
    "occupancies": [
      {
        "occupancy_index": 0,
        "adults": 2
      }
    ],
    "currency": "USD",
    "agency": "56458",
    "nationality": "IT"
  },
  "booked_rates": [
    {
      "rate_identifier": "d14f44aa839e3d67b7bc1e6c1bce7953",
      "amount": {
        "price": 110,
        "vat": {
          "value": 0,
          "included": false
        }
      },
      "quantity": 1,
      "guest_details": [
        {
          "leader": true,
          "first_name": "Veronika Test Booking Nuitee",
          "last_name": "Surname Test Booking Nuitee"
        }
      ]
    }
  ]
}

Book Hotel

{
  "availability_request": {
    "property_id": 23755,
    "checkin": "2025-01-13",
    "checkout": "2025-01-14",
    "occupancies": [
      {
        "occupancy_index": 0,
        "adults": 2
      }
    ],
    "currency": "USD",
    "agency": "56458",
    "nationality": "IT"
  },
  "booked_rates": [
    {
      "rate_identifier": "d14f44aa839e3d67b7bc1e6c1bce7953",
      "amount": {
        "price": 110,
        "vat": {
          "value": 0,
          "included": false
        }
      },
      "quantity": 1,
      "guest_details": [
        {
          "leader": true,
          "first_name": "Veronika Test Booking Nuitee",
          "last_name": "Surname Test Booking Nuitee"
        }
      ]
    }
  ],
  "client_booking_reference": "nuitee-test-1",
  "customer_remarks": "Test Booking Nuitee",
  "payment_method": {
    "credit_card": {
      "number": "4111111111111111",
      "holder_name": "Nuitee",
      "expiration_month": 10,
      "expiration_year": 26,
      "cvv": 645
    }
  }
}

Cancel Booking

{
  "booking_id": 83314
}

Testing

Run the test suite to verify all tools are working:

node test-server.js

Development

Build

npm run build

Watch Mode

npm run dev

License

This project is licensed under the MIT License.