# Rizerve MCP Server

[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue)](https://modelcontextprotocol.io)
[![API](https://img.shields.io/badge/API-v1.0-green)](https://api.rizerve.io/v1/health)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![npm](https://img.shields.io/badge/npm-install-red)](https://www.npmjs.com/)

MCP server for the [Rizerve](https://rizerve.io) direct booking platform. Manage properties, bookings, availability, iCal sync, analytics, and webhooks through AI assistants.

## Install

```bash
git clone https://github.com/panoskiriakopoulos-sys/rizerve-mcp-server.git
cd rizerve-mcp-server
npm install && npm run build
```

## Setup

Get your API key from **Rizerve Dashboard → Integrations → API Access**.

### Claude Desktop

```json
{
  "mcpServers": {
    "rizerve": {
      "command": "node",
      "args": ["/path/to/rizerve-mcp-server/dist/index.js"],
      "env": {
        "RIZERVE_API_KEY": "rz_xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Cursor / Windsurf

```json
{
  "mcpServers": {
    "rizerve": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/rizerve-mcp-server",
      "env": {
        "RIZERVE_API_KEY": "rz_xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

---

## What You Can Ask

Connect to any MCP-compatible client and ask:

- *"Show me all my properties"*
- *"What bookings check in this week?"*
- *"Create a new property in Crete for €120/night"*
- *"Is the beach villa available July 5–10?"*
- *"Block August 1–15 for maintenance on all properties"*
- *"Import my Airbnb calendar into the villa"*
- *"What's our occupancy rate this month?"*
- *"Create a webhook that notifies Slack on new bookings"*
- *"How much revenue did we make in Q2?"*
- *"Show me all bookings from maria@example.com"*

---

## Tool Reference

### Properties (5 tools)

| Tool | Arguments | Description |
|------|-----------|-------------|
| `rizerve_list_properties` | `page`, `limit`, `published_only` | List all properties with full details, prices, amenities |
| `rizerve_get_property` | `slug` | Get single property by its public slug |
| `rizerve_create_property` | `name`\*, `price_per_night`\*, `location`, `bedrooms`, `amenities`, ... | Create a new property listing |
| `rizerve_update_property` | `slug`, then any field to change | Update property fields (partial update) |
| `rizerve_delete_property` | `slug` | Permanently delete property + all related data ⚠️ |

### Bookings (4 tools)

| Tool | Arguments | Description |
|------|-----------|-------------|
| `rizerve_list_bookings` | `status`, `property_slug`, `check_in_from`, `check_in_to`, `page`, `limit` | List bookings with filters |
| `rizerve_get_booking` | `id` | Get single booking by UUID |
| `rizerve_create_booking` | `property_id`\*, `guest_name`\*, `check_in`\*, `check_out`\*, `total_price`\*, `guest_email`, `guest_phone`, `guests`, `notes` | Create a new booking — auto-enforces minimum stay |
| `rizerve_update_booking_status` | `id`, `status` | Transition: pending→confirmed/cancelled, confirmed→cancelled/completed |

### Availability (3 tools)

| Tool | Arguments | Description |
|------|-----------|-------------|
| `rizerve_get_availability` | `slug`, `check_in`, `check_out` | Check if a property is available for a date range |
| `rizerve_block_date` | `slug`, `date`, `available`, `reason` | Block or unblock a single date |
| `rizerve_batch_set_availability` | `ranges[]` (`property_id`, `date_from`, `date_to`, `available`, `reason`) | Bulk block/unblock up to 50 date ranges |

### iCal Feeds (4 tools)

| Tool | Arguments | Description |
|------|-----------|-------------|
| `rizerve_list_ical_feeds` | `slug` | List imported calendar feeds (Airbnb, Booking.com, VRBO) |
| `rizerve_import_ical_feed` | `slug`, `url`, `source` | Import external iCal feed — auto-syncs within minutes |
| `rizerve_export_ical` | `slug` | Get the public iCal URL to share with OTAs |
| `rizerve_delete_ical_feed` | `slug`, `feed_id` | Remove imported feed and its dates ⚠️ |

### Analytics (3 tools)

| Tool | Arguments | Description |
|------|-----------|-------------|
| `rizerve_get_property_stats` | `slug`, `period` | Page views, bookings, conversion, revenue, occupancy |
| `rizerve_get_revenue_report` | `period`, `group_by` | Revenue breakdown by day/week/month/property |
| `rizerve_get_occupancy_report` | `period`, `property_slug` | Occupancy rates across properties |

### Webhooks & Guests (3 tools)

| Tool | Arguments | Description |
|------|-----------|-------------|
| `rizerve_create_webhook` | `url`, `events[]` | Register webhook for `booking.created`, `booking.status_changed`, `availability.updated` |
| `rizerve_list_webhooks` | — | List registered webhooks with failure stats |
| `rizerve_delete_webhook` | `id` | Remove webhook |
| `rizerve_lookup_guest` | `email` | Find all bookings for a guest by email |

**19 tools total** — full CRUD across properties, bookings, availability, iCal, analytics, webhooks, and guest history.

---

## Configuration

| Env Var | Default | Description |
|---------|---------|-------------|
| `RIZERVE_API_KEY` | *required* | API key from Rizerve Dashboard → Integrations → API Access |
| `RIZERVE_API_URL` | `https://api.rizerve.io/v1` | API base URL (change for staging/testing) |
| `TRANSPORT` | `stdio` | `stdio` for local MCP clients, `http` for remote access |
| `PORT` | `3000` | HTTP port when `TRANSPORT=http` |

---

## API Compatibility

This server targets **Rizerve API v1**. All prices are in the property's configured currency (face value, not cents). Response format is raw JSON arrays/objects — the MCP server transparently wraps them for tool compatibility.

Full API reference: [`rizerve-api-docs.md`](../rizerve-api-docs.md)

---

## Development

```bash
# Install
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run with debug logging
DEBUG=* npm start
```

### Project Structure

```
src/
├── index.ts           # MCP server entry, registers all tools
├── constants.ts       # API URL, response formats, valid values
├── types.ts           # TypeScript interfaces matching v1 API responses
├── services/
│   └── api-client.ts  # HTTP client, response wrapping, error handling
├── tools/
│   ├── properties.ts  # Property CRUD tools
│   ├── bookings.ts    # Booking CRUD + status machine tools
│   ├── availability.ts # Date blocking + batch tools
│   ├── ical.ts        # iCal import/export tools
│   └── analytics.ts   # Revenue, occupancy, stats tools
└── schemas/
    ├── common.ts      # Shared Zod schemas (pagination, response format)
    ├── properties.ts  # Property input validation
    ├── bookings.ts    # Booking input validation
    ├── availability.ts # Availability input validation
    ├── ical.ts        # iCal input validation
    └── analytics.ts   # Analytics input validation
```

---

## License

MIT © [Osolvo Ltd](https://osolvo.com)