Beds24 MCP Server

A comprehensive Model Context Protocol (MCP) server for the Beds24 property management API. This server provides Claude with access to Beds24 operations including bookings, properties, availability management, messaging, and more.

Features

Booking Management

• beds24-get-bookings - Retrieve bookings with filtering by date, status, and search criteria
• beds24-set-booking - Create, update, or modify booking details

Availability & Rates

• beds24-get-availabilities - Retrieve availability and pricing information
• beds24-set-rates - Set or update rates for properties and time periods

Property Management

• beds24-get-properties - Retrieve list of all properties
• beds24-get-property - Get detailed information about a specific property
• beds24-set-property - Update property details

Account Management

• beds24-get-account - Retrieve account information and settings

Communications

• beds24-get-messages - Retrieve messages and communications from bookings
• beds24-set-message - Send or update a message for a booking

Invoice Management

• beds24-get-invoices - Retrieve invoice information for bookings

Room Management

• beds24-get-room-dates - Retrieve room-specific date information (blocked dates, etc.)
• beds24-set-room-dates - Set room availability and blocking dates
• beds24-get-daily-price-setup - Get daily pricing setup and structure

Installation

Prerequisites

• Node.js >= 18.0.0
• npm or yarn

Setup Steps

1. Navigate to the project directory:

cd nova-beds24

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Configure your Beds24 API credentials:
   • Get your API Key from your Beds24 account settings
   • Get your Property Key for the properties you want to manage

Configuration

Environment Variables

Set these environment variables before running the server:

• NOVA_API_KEY - Nova-Mind Cloud API key (optional, for development)
• NOVA_CLIENT_NAME - Nova-Mind Cloud client name (optional, for development)
• NOVA_CLOUD_URL - Nova-Mind Cloud URL (optional, defaults to https://api.nova-mind.cloud/mcp)

Beds24 Authentication

When calling any tool, you'll need to provide:

• apiKey - Your Beds24 API key
• propKey - Your Beds24 property key (for property-specific operations)

Usage Examples

Get Bookings

{
  "apiKey": "your_beds24_api_key",
  "propKey": "your_property_key",
  "arrivalFrom": "2024-01-01",
  "arrivalTo": "2024-12-31",
  "limit": 50
}

Create a Booking

{
  "apiKey": "your_beds24_api_key",
  "propKey": "your_property_key",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "roomId": "room123",
  "arrival": "2024-06-01",
  "departure": "2024-06-05",
  "numAdult": 2,
  "numChild": 0
}

Check Availability

{
  "checkIn": "2024-06-01",
  "checkOut": "2024-06-05",
  "propId": "property123",
  "numAdult": 2,
  "numChild": 0
}

Set Rates

{
  "apiKey": "your_beds24_api_key",
  "propKey": "your_property_key",
  "roomId": "room123",
  "dateFrom": "2024-06-01",
  "dateTo": "2024-06-30",
  "price": 150.00,
  "minStay": 1
}

Date Format

All dates should be in one of these formats:

• ISO format: YYYY-MM-DD (e.g., 2024-06-01)
• Beds24 format: YYYYMMDD (e.g., 20240601)

The server will automatically convert dates to the Beds24 API format (YYYYMMDD).

Running the Server

Development Mode

npm run dev

Production Mode

npm start

Or via stdio:

node dist/index.js

API Endpoints

The server connects to the following Beds24 API endpoints:

• https://api.beds24.com/json/getBookings
• https://api.beds24.com/json/setBooking
• https://api.beds24.com/json/getAvailabilities
• https://api.beds24.com/json/setRate
• https://api.beds24.com/json/getProperties
• https://api.beds24.com/json/getProperty
• https://api.beds24.com/json/setProperty
• https://api.beds24.com/json/getAccount
• https://api.beds24.com/json/getMessages
• https://api.beds24.com/json/setMessage
• https://api.beds24.com/json/getInvoices
• https://api.beds24.com/json/getRoomDates
• https://api.beds24.com/json/setRoomDates
• https://api.beds24.com/json/getDailyPriceSetup

Error Handling

The server provides comprehensive error handling:

• Invalid HTTP responses are caught and reported
• Beds24 API errors are extracted and displayed
• Connection errors are logged with helpful messages
• All errors include descriptive messages for debugging

Architecture

Core Components

1. Authentication Module - Handles Nova-Mind Cloud validation
2. Request Handler - Makes authenticated requests to Beds24 API
3. Date Formatter - Converts dates to Beds24 format (YYYYMMDD)
4. Tool Registry - Defines all available MCP tools with schemas
5. Tool Executors - Implements business logic for each tool

Type Safety

The server is written in TypeScript with strict type checking enabled:

• All parameters are properly typed
• Input validation through JSON schemas
• Comprehensive error handling with proper type casting

Security Considerations

• API keys should never be hardcoded; use environment variables
• Consider using Beds24's IP whitelist feature
• The server validates authentication before starting in production
• All requests to Beds24 API use HTTPS

Troubleshooting

Authentication Errors

If you see "Authentication failed" errors:

1. Verify your Beds24 API key is correct
2. Check that your property key is valid
3. Ensure your Beds24 account has API access enabled

Connection Issues

If the server can't connect to Beds24:

1. Check your internet connection
2. Verify the Beds24 API is accessible from your network
3. Check for any firewall restrictions

Date Format Issues

Always use either YYYY-MM-DD or YYYYMMDD format for dates. The server will handle conversion.

Building for Production

1. Build the TypeScript:

npm run build

2. The compiled JavaScript will be in the dist/ directory

3. For deployment, only include:

   • dist/ folder
   • package.json
   • package-lock.json

Dependencies

• @modelcontextprotocol/sdk - MCP framework
• TypeScript development dependencies for building

License

Licensed under LicenseRef-NMCL

Support

For issues or feature requests, please contact the Nova-Mind Cloud team or submit an issue to the repository.

Changelog

Version 1.0.0 (Initial Release)

• Complete Beds24 API integration
• 14 MCP tools for property management
• Full TypeScript implementation
• Nova-Mind Cloud authentication
• Comprehensive error handling