Hostaway Mcp

@prosperkartik/hostaway-mcp

用于 Hostaway PMS 的模型上下文协议（MCP）服务 — 将 Claude 连接到您的度假租赁运营。

@prosperkartik/hostaway-mcp 可将 Claude（通过 Claude Code、Claude Desktop 或任何兼容 MCP 的客户端）连接到您的 Hostaway 账户，访问房源、预订、日历可用情况、宾客消息和财务信息。作者是一名工程师，自 2022 年起一直为短租运营商在生产环境中集成 Hostaway、Ciirus 和主要 OTA API（Airbnb、VRBO、Booking.com、Expedia、Marriott）。

Hostaway 是 Hostaway Inc. 的商标。本项目由社区开发，与 Hostaway 无关，也未获其认可。

为什么选择此服务

有三个原因：

1. 工具覆盖范围广。 提供 10 个只读工具，涵盖房源、预订、日历、对话、财务和健康检查，比此领域其他社区 MCP 服务覆盖面更广。
2. 认证体验更简洁。 使用 Hostaway 在 API 设置页面提供的两项凭据——Account ID 和 API Key——并在内部处理 OAuth 令牌交换。无需先去别处生成持有者令牌。
3. 由 API 使用者打造。 作者拥有 3 年以上 Hostaway / Ciirus 生产环境集成经验，设计决策均基于这些实践。工具对应真实运营工作流，而非仅仅映射 REST 端点。

工具（v0.1）

v0.1 的所有工具均为只读。写入操作将在后续版本中推出，并要求明确确认。

工具	描述
whoami	健康检查 — 返回已连接账户的数量（房源、预订、对话、业主报表、用户）。先运行此工具，确认设置正常。
list_listings	列出账户中的房源
get_listing	单个房源的完整详情 — 位置、容量、定价、声誉、渠道 URL
list_reservations	列出预订，可选择按抵达日期范围和状态筛选
get_reservation	单个预订的完整详情 — 宾客、日期、定价、渠道
list_calendar	指定日期范围内某房源每日的可用情况 — 回答 “房源 X 在 A 到 B 期间有空吗？”
list_conversations	列出宾客消息对话串，并显示未读状态和最近活动
list_unread_conversations	仅列出有未读宾客消息的对话 — 回答 “谁还在等回复？”
get_conversation_messages	获取单个对话的完整消息记录
list_owner_statements	列出业主财务报表

快速开始

1. 获取 Hostaway API 凭据

在您的 Hostaway 运营账户中，前往 Settings → Hostaway API。生成 API 凭据后，您将获得 Account ID 和 API Key。

2. 添加到 Claude Code

claude mcp add hostaway \
  --scope user \
  -e HOSTAWAY_ACCOUNT_ID=your-account-id \
  -e HOSTAWAY_API_KEY=your-api-key \
  -- npx -y @prosperkartik/hostaway-mcp

（或者使用 --scope local，仅为当前项目安装。）

3. 或添加到 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS），并添加：

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "@prosperkartik/hostaway-mcp"],
      "env": {
        "HOSTAWAY_ACCOUNT_ID": "your-account-id",
        "HOSTAWAY_API_KEY": "your-api-key"
      }
    }
  }
}

重启 Claude Desktop。Hostaway 工具将显示在工具选择器中。

4. 试用

可以向 Claude 提问，例如：

• “运行 whoami，确认 Hostaway 已连接。”
• “列出我的 Hostaway 房源。”
• “下周有哪些预订要入住？”
• “房源 12345 在 5 月 10 日至 17 日有空吗？”
• “我有未读的宾客消息吗？”
• “显示我与 [宾客] 的对话。”

示例输出（占位数据）

> List my Hostaway listings.

Found 3 listings:

| ID    | Name              | Location          | Beds | Baths | Capacity | Status |
|-------|-------------------|-------------------|------|-------|----------|--------|
| 10001 | Sample Apt 2BR    | Sample City, US   | 2    | 2     | 4        | active |
| 10002 | Sample Loft       | Sample City, US   | 1    | 1     | 2        | active |
| 10003 | Sample Beachfront | Sample Beach, US  | 3    | 2     | 6        | active |

> Is listing 10001 available May 10–17?

# Calendar for listing 10001
8 days returned (2026-05-10 → 2026-05-17)  ·  6 available, 2 reserved, 0 blocked

| Date       | Available | Status   | Price | Min stay | Reserved | Blocked | Note |
|------------|-----------|----------|-------|----------|----------|---------|------|
| 2026-05-10 | ✓         | available| 220   | 2        | 0        | 0       |      |
| 2026-05-11 | ✓         | available| 220   | 2        | 0        | 0       |      |
| 2026-05-12 | ✗         | reserved | 220   | 2        | 1        | 0       |      |
| ...                                                                            |

配置

环境变量	必填	描述
HOSTAWAY_ACCOUNT_ID	是	你的 Hostaway 账户 ID（用作 OAuth client_id）
HOSTAWAY_API_KEY	是	你的 Hostaway API 密钥（用作 OAuth client_secret）

服务会在启动时用这些信息换取 bearer token，并在进程运行期间将其缓存于内存中。

本地开发

git clone https://github.com/prosperkartik/hostaway-mcp.git
cd hostaway-mcp
npm install
cp .env.example .env  # fill in credentials
npm run build
npm start

通过 tsx 热重载：

npm run dev

路线图

• v0.1 — 提供 10 个只读工具，涵盖房源、预订、日历、对话、财务和健康检查
• v0.2 — 任务（list_tasks、get_task）；取消政策；读取自定义字段
• v0.3 — 读取房客付款信息；读取 Webhook
• v0.4+ — 写入操作（发送房客消息、更新日历屏蔽时段、创建任务），需通过 confirm: true 明确确认

有需求？提交 issue或发起讨论。

安全性

• 凭据仅存于环境变量中——此服务绝不会将其写入磁盘
• bearer token 存于进程内存中；不会持久化存储
• v0.1 全程只读；此代码库中的任何内容都无法修改 Hostaway 数据
• 对于管理多个房源的运营者：Hostaway API 返回的数据仅限于你提供凭据所对应的账户，因此无法跨账户访问

贡献

欢迎提交 issue 和 PR。代码库规模小且易于阅读；可从 src/index.ts 开始。

许可证

MIT — 详见 LICENSE。

作者

由 Kartik Vats（@prosperkartik）开发——Kodeit 的 AI 工程师。拥有三年 PMS / OTA 集成和 LLM 工具开发的生产实践经验。

如果你是度假租赁运营者或酒店科技团队，希望获得将 AI 接入运营流程的帮助，请通过 kodeit.io 联系，或发送邮件至 [email protected]。