内容
# Rizerve MCP 服务器
[](https://modelcontextprotocol.io)
[](https://api.rizerve.io/v1/health)
[](https://nodejs.org)
[](https://www.npmjs.com/)
用于 [Rizerve](https://rizerve.io) 直接预订平台的 MCP 服务器。通过 AI 助手管理房产、预订、可用性、iCal 同步、分析和 Webhook。
## 安装
```bash
git clone https://github.com/panoskiriakopoulos-sys/rizerve-mcp-server.git
cd rizerve-mcp-server
npm install && npm run build
```
## 设置
从 **Rizerve 仪表盘 → 集成 → API 访问** 获取您的 API 密钥。
### Claude 桌面版
```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"
}
}
}
}
```
---
## 您能询问的内容
连接任何支持 MCP 的客户端并询问：
- *"显示我所有的房产"*
- *"本周有哪些预订？"*
- *"在 Crete 创建一个新房产，价格为 €120/晚"*
- *"海滩别墅在 7 月 5 日至 10 日期间可用吗？"*
- *"在所有房产上屏蔽 8 月 1 日至 15 日进行维护"*
- *"将我的 Airbnb 日历导入别墅"*
- *"这个月的入住率是多少？"*
- *"创建一个 Webhook，在有新预订时通知 Slack"*
- *"我们在第二季度赚了多少钱？"*
- *"显示来自 maria@example.com 的所有预订"*
---
## 工具参考
### 房产（5 个工具）
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `rizerve_list_properties` | `page`, `limit`, `published_only` | 列出所有具有完整详情、价格、设施的房产 |
| `rizerve_get_property` | `slug` | 通过公共 slug 获取单个房产 |
| `rizerve_create_property` | `name`\*, `price_per_night`\*, `location`, `bedrooms`, `amenities`, ... | 创建新的房产列表 |
| `rizerve_update_property` | `slug`, 然后是任何要更改的字段 | 更新房产字段（部分更新） |
| `rizerve_delete_property` | `slug` | 永久删除房产及其所有相关数据 ⚠️ |
### 预订（4 个工具）
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `rizerve_list_bookings` | `status`, `property_slug`, `check_in_from`, `check_in_to`, `page`, `limit` | 列出具有筛选条件的预订 |
| `rizerve_get_booking` | `id` | 通过 UUID 获取单个预订 |
| `rizerve_create_booking` | `property_id`\*, `guest_name`\*, `check_in`\*, `check_out`\*, `total_price`\*, `guest_email`, `guest_phone`, `guests`, `notes` | 创建新的预订 — 自动强制执行最低停留时间 |
| `rizerve_update_booking_status` | `id`, `status` | 状态转换：pending→confirmed/cancelled，confirmed→cancelled/completed |
### 可用性（3 个工具）
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `rizerve_get_availability` | `slug`, `check_in`, `check_out` | 检查房产在某日期范围内的可用性 |
| `rizerve_block_date` | `slug`, `date`, `available`, `reason` | 屏蔽或取消单个日期 |
| `rizerve_batch_set_availability` | `ranges[]` (`property_id`, `date_from`, `date_to`, `available`, `reason`) | 批量屏蔽/取消最多 50 个日期范围 |
### iCal 订阅源（4 个工具）
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `rizerve_list_ical_feeds` | `slug` | 列出导入的日历订阅源（Airbnb，Booking.com，VRBO） |
| `rizerve_import_ical_feed` | `slug`, `url`, `source` | 导入外部 iCal 订阅源 — 在几分钟内自动同步 |
| `rizerve_export_ical` | `slug` | 获取公共 iCal URL 以与 OTAs 共享 |
| `rizerve_delete_ical_feed` | `slug`, `feed_id` | 删除导入的订阅源及其日期 ⚠️ |
### 分析（3 个工具）
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `rizerve_get_property_stats` | `slug`, `period` | 页面浏览量、预订量、转化率、收入、入住率 |
| `rizerve_get_revenue_report` | `period`, `group_by` | 按日/周/月/房产划分的收入明细 |
| `rizerve_get_occupancy_report` | `period`, `property_slug` | 房产的入住率 |
### Webhook 和客人（3 个工具）
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `rizerve_create_webhook` | `url`, `events[]` | 为 `booking.created`、`booking.status_changed`、`availability.updated` 注册 Webhook |
| `rizerve_list_webhooks` | — | 列出已注册的 Webhook 及失败统计 |
| `rizerve_delete_webhook` | `id` | 删除 Webhook |
| `rizerve_lookup_guest` | `email` | 通过电子邮件查找客人的所有预订 |
**总共 19 个工具** — 跨房产、预订、可用性、iCal、分析、Webhook 和客人历史的完整 CRUD。
---
## 配置
| 环境变量 | 默认值 | 描述 |
|---------|---------|-------------|
| `RIZERVE_API_KEY` | *必填* | 来自 Rizerve 仪表盘 → 集成 → API 访问的 API 密钥 |
| `RIZERVE_API_URL` | `https://api.rizerve.io/v1` | API 基本 URL（用于分段/测试） |
| `TRANSPORT` | `stdio` | `stdio` 用于本地 MCP 客户端，`http` 用于远程访问 |
| `PORT` | `3000` | 当 `TRANSPORT=http` 时的 HTTP 端口 |
---
## API 兼容性
此服务器针对 **Rizerve API v1**。所有价格均采用房产的配置货币（面值，非美分）。响应格式为原始 JSON 数组/对象 — MCP 服务器透明地将它们封装为工具兼容。
完整 API 参考：[`rizerve-api-docs.md`](../rizerve-api-docs.md)
---
## 开发
```bash
# 安装
npm install
# 构建
npm run build
# 监视模式
npm run dev
# 运行调试日志
DEBUG=* npm start
```
### 项目结构
```
src/
├── index.ts # MCP 服务器入口，注册所有工具
├── constants.ts # API URL、响应格式、有效值
├── types.ts # TypeScript 接口，匹配 v1 API 响应
├── services/
│ └── api-client.ts # HTTP 客户端，响应封装，错误处理
├── tools/
│ ├── properties.ts # 房产 CRUD 工具
│ ├── bookings.ts # 预订 CRUD + 状态机工具
│ ├── availability.ts # 日期屏蔽 + 批量工具
│ ├── ical.ts # iCal 导入/导出工具
│ └── analytics.ts # 收入、入住率、统计工具
└── schemas/
├── common.ts # 共享 Zod 模式（分页、响应格式）
├── properties.ts # 房产输入验证
├── bookings.ts # 预订输入验证
├── availability.ts # 可用性输入验证
├── ical.ts # iCal 输入验证
└── analytics.ts # 分析输入验证
```
---
## 许可证
MIT © [Osolvo Ltd](https://osolvo.com)
