hostaway

hostaway-mcp

一个开源的 Model Context Protocol (MCP) 服务，可将 Claude Desktop、Claude Code 和 Cursor 等 AI 助手连接到 Hostaway 房源管理 API。使用自然语言查询预订、房源、日历、财务信息和房客对话。

快速开始

1. 在 Hostaway 控制面板的 Settings > API 下获取 Account ID 和 Client Secret
2. 确保已安装 Node.js 18+
3. 选择下方的 AI 客户端并添加配置——无需克隆或构建

设置

Claude Desktop（Mac 和 Windows）

打开 Claude Desktop 配置文件：

• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

添加以下内容（如果已配置其他服务，请与现有的 mcpServers 合并）：

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "@matt-long-plux/hostaway-mcp"],
      "env": {
        "HOSTAWAY_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
        "HOSTAWAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

重启 Claude Desktop，即可开始使用。

Claude Code

选项 1 — CLI 命令（最快）：

claude mcp add hostaway \
  -e HOSTAWAY_ACCOUNT_ID=YOUR_ACCOUNT_ID \
  -e HOSTAWAY_CLIENT_SECRET=YOUR_CLIENT_SECRET \
  -- npx -y @matt-long-plux/hostaway-mcp

选项 2 — 在项目根目录中创建 .mcp.json（便于与团队成员共享）：

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "@matt-long-plux/hostaway-mcp"],
      "env": {
        "HOSTAWAY_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
        "HOSTAWAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Cursor

将相同的配置添加到项目的 .cursor/mcp.json，或者前往 Cursor Settings > MCP Servers > Add Server 并粘贴：

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "@matt-long-plux/hostaway-mcp"],
      "env": {
        "HOSTAWAY_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
        "HOSTAWAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

更新

如果你之前通过 npx 安装过版本，系统可能缓存了旧副本。若要更新到最新版本：

npx clear-npx-cache

然后重启 AI 客户端（Claude Desktop、Cursor 等）。下次启动时将自动获取最新版本。

或者，你可以在配置中固定使用 @latest，以便每次重启时都获取最新版本：

"args": ["-y", "@matt-long-plux/hostaway-mcp@latest"]

工具参考

预订

工具	描述	关键参数
list_reservations	按筛选条件列出预订	listingMapId、dateFrom、dateTo、status、channelId、limit
get_reservation	获取完整的预订详情	reservationId（必填）
update_reservation_host_note	更新内部房东备注	reservationId、hostNote（必填）
list_reservations_by_property	按房源分组列出当前和即将到来的预订	无

房源

工具	描述	关键参数
list_listings	列出所有有效房源及其元数据	includeArchived
get_listing	获取完整的房源详情	listingId（必填）
get_listing_custom_fields	以名称-值映射形式获取自定义字段值	listingId（必填）

日历

工具	描述	关键参数
get_calendar	查询可订状态和价格日历	listingId、startDate、endDate（均为必填）
get_gap_nights	查找预订之间较短的空档日期	listingId（必填）、startDate、endDate、maxGapLength
create_calendar_block	在日历中屏蔽日期	listingId、startDate、endDate（必填）、note
delete_calendar_block	移除日历屏蔽	listingId、calendarBlockId（必填）

财务信息

工具	描述	关键参数
get_reservation_financials	获取预订的财务明细	reservationId（必填）
get_revenue_summary	汇总所有房源的收入	dateFrom、dateTo（必填）、listingId
get_payout_report	获取用于对账的付款报告	dateFrom、dateTo（必填）、channelId

对话

工具	描述	关键参数
list_conversations	最近的房客对话	listingId、limit、unreadOnly
get_conversation	完整消息线程	conversationId（必填）
send_message	向房客发送消息	conversationId、message（必填）

只读模式

设置 HOSTAWAY_READ_ONLY=true 可禁用所有写入/修改工具。启用后，以下工具将返回错误，而不会执行：

• update_reservation_host_note
• create_calendar_block
• delete_calendar_block
• send_message

这适用于共享账户，或需要防止意外修改的情况。

环境变量

变量	必填	描述
HOSTAWAY_ACCOUNT_ID	是	你的 Hostaway 账户 ID（整数）
HOSTAWAY_CLIENT_SECRET	是	你的 Hostaway API 客户端密钥
HOSTAWAY_READ_ONLY	否	设置为 true 以禁用写入操作
HOSTAWAY_CACHE_TTL	否	令牌缓存 TTL（秒，默认值：240）

示例查询

连接后，可以尝试向 Claude 提问：

• “显示所有即将到来的预订”
• “下个月我的房源入住情况如何？”
• “查找未来 90 天内所有房源的空档夜晚”
• “我上个月赚了多少收入？”
• “显示未读房客消息”
• “预订 12345 的财务情况如何？”
• “生成 3 月 Airbnb 订单的付款报告”

参与贡献

欢迎反馈和拉取请求！请在 GitHub 上提交问题，或发送邮件至 [email protected]。

许可证

MIT