npm package: @flyguy729/hostex-mcp-server
Description: Model Context Protocol (MCP) server for Hostex API - Enables AI assistants to manage vacation rental properties
Author: Igel
Latest version: 1.0.0

# 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](https://hostex.io)
   - 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:

```json
{
  "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:

```bash
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

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

### Running Locally

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

# Run the server
npm start
```

### Testing with npm link

```bash
npm link
hostex-mcp-server
```

## CLI Commands

```bash
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](https://github.com/flyguy729/hostex-mcp-server/issues)

For Hostex API documentation, visit: [Hostex API Docs](https://api.hostex.com/docs)