Hostex MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with the Hostex API for vacation rental property management.

Features

• 🏠 Property Management: Query and manage vacation rental properties
• 📅 Availability Checking: Find empty/available properties with detailed guidance
• 📖 Reservation Management: View and manage bookings with comprehensive parameter warnings
• 💬 Guest Communication: Send messages to guests
• ⭐ Review Management: Handle guest reviews and ratings
• 💰 Pricing Control: Update property prices and restrictions
• 🛠️ Smart Tool Advisor: Get recommendations on which tool to use based on your intent

Installation

Quick Setup

1. Get your Hostex API key:

   • Log in to your Hostex account
   • Navigate to Settings > API
   • Generate or copy your API key

2. Add the Hostex MCP server to your Claude configuration:

Edit your Claude configuration file:

• On macOS/Linux: ~/.claude/claude.json
• On Windows: %APPDATA%\Claude\claude.json

Add the following configuration:

{
  "mcpServers": {
    "hostex": {
      "command": "npx",
      "args": ["-y", "@flyguy729/hostex-mcp-server"],
      "env": {
        "HOSTEX_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Replace "your-api-key-here" with your actual Hostex API key

4. Restart Claude to apply the changes

That's it! The Hostex MCP server will now be available in Claude.

Setup Instructions Command

For detailed setup instructions, you can also run:

npx @flyguy729/hostex-mcp-server setup

This will display step-by-step configuration instructions.

Usage in Claude

Once configured, you can ask Claude to:

• "Check which properties are empty today"
• "Show me current bookings"
• "Update prices for next week"
• "Send a message to the guest in room 101"
• "Show pending reviews"

Tool Advisor

If you're unsure which tool to use, the server includes a helpful advisor:

Ask Claude: "I want to see which rooms don't have guests"

The advisor will recommend the best tools and provide parameter guidance.

Important Notes

⚠️ Common Pitfalls and Solutions

1. Pagination Defaults: Most query endpoints default to 20 results. Always use limit=100, offset=0 to get all results.

2. Reservation Status: Check the in_reservation_box field:

   • true = reservation is NOT active (not blocking calendar)
   • false = reservation IS active (blocking calendar)

3. Availability vs Occupancy: Properties with available: false might be:

   • Actually occupied
   • Blocked for maintenance
   • Having guest issues
   • System sync blocks

4. Date Parameters: For accurate reservation queries, always specify ALL FOUR date parameters:

   • start_check_in_date
   • end_check_in_date
   • start_check_out_date
   • end_check_out_date

API Documentation

The server implements all Hostex API endpoints with enhanced descriptions and parameter guidance. Each tool includes:

• Clear warnings about required parameters
• Usage examples for common scenarios
• Cross-referencing guidance
• Rate limit information

Development

Building from Source

git clone https://github.com/flyguy729/hostex-mcp-server.git
cd hostex-mcp-server
npm install
npm run build

Running Locally

# Set your API key
export HOSTEX_API_KEY="your-api-key"

# Run the server
npm start

Testing with npm link

npm link
hostex-mcp-server

CLI Commands

npx @flyguy729/hostex-mcp-server              # Run the MCP server (default)
npx @flyguy729/hostex-mcp-server setup        # Show setup instructions
npx @flyguy729/hostex-mcp-server help         # Show help message
npx @flyguy729/hostex-mcp-server version      # Show version information

Environment Variables

• HOSTEX_API_KEY: Your Hostex API key (required)
• HOSTEX_API_BASE_URL: Override the API base URL (optional, defaults to https://api.hostex.com)

Troubleshooting

"HOSTEX_API_KEY environment variable is not set"

Make sure you've added your API key to the Claude configuration file or set it as an environment variable.

"No properties found"

Check if you're using the correct pagination parameters (limit=100, offset=0).

Rate Limit Errors

• Update operations: 120 requests per minute
• Reservation creation: 60 requests per minute
• Message sending: 5 requests per 5 seconds + 1,000 per hour

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

For issues and feature requests, please visit: GitHub Issues

For Hostex API documentation, visit: Hostex API Docs