Content
# Rizerve MCP Server
[](https://modelcontextprotocol.io)
[](https://api.rizerve.io/v1/health)
[](https://nodejs.org)
[](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)
