hostaway

hostaway-mcp

面向酒店业的 Hostaway 只读 MCP 服务。

本仓库仅负责运营者产品：本地/npm stdio、六个只读工具，不包含 Cloudflare Worker，也不包含 Seascape 预订界面。

V1 目标

让 Codex 和 Claude 能在实际的 Hostaway 工作流中发挥作用，无需每次都手动接线调用原始 API。

V1 刻意保持精简：

• 仅支持只读
• 提供面向酒店业的原生工具，而非与原始端点一一对应
• 针对对话上下文、预订查询和房源查询进行优化

V1 的确切范围

• list_unread_guest_threads
• get_conversation_context
• get_reservation_brief
• get_listing_brief
• search_reservations
• search_conversations

本地开发

npm install
npm test
npm run check
npm run build

在本地运行 stdio 服务：

HOSTAWAY_API_TOKEN=your-token-here node dist/cli.js

创建本地 npm 软件包 tarball：

npm pack

发布后，无需克隆即可运行：

npx hostaway-mcp

MCP 客户端接入

对于本地 MCP 客户端，通过环境变量提供 HOSTAWAY_API_TOKEN，并通过 stdio 启动已发布的 npm 软件包。

以下代码片段固定使用当前已发布的版本：

[email protected]

升级时，请有意更新该版本。

Claude Desktop（macOS）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json。

如果已有 preferences 等顶层键，请保留，并在同级添加 mcpServers：

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "HOSTAWAY_API_TOKEN": "your-token-here"
      }
    }
  }
}

保存文件后，重启 Claude Desktop。

Codex

编辑 ~/.codex/config.toml 并添加：

[mcp_servers.hostaway]
command = "npx"
args = ["-y", "[email protected]"]

[mcp_servers.hostaway.env]
HOSTAWAY_API_TOKEN = "your-token-here"

验证服务已注册：

codex mcp list

本地构建的 CLI

如果要运行仓库检出版本而非 npm，请让客户端直接指向构建后的 CLI：

{
  "command": "node",
  "args": ["/absolute/path/to/hostaway-mcp/dist/cli.js"],
  "env": {
    "HOSTAWAY_API_TOKEN": "your-token-here"
  }
}

环境变量

变量	必填	默认值	描述
HOSTAWAY_API_TOKEN	是	—	用于对所有请求进行身份验证的 Hostaway API 令牌。
HOSTAWAY_BASE_URL	否	Hostaway 生产环境 URL	覆盖 API 基础 URL（适用于测试）。

V1 不包含的目标

• 发送宾客消息
• 修改预订或房源
• Cloudflare Worker 传输
• Seascape 预订/分销流程
• Webhook 接收
• 后台同步流水线
• 仪表板或业主报告
• 通用 REST 到 MCP 代理覆盖

源码设计

参见 docs/designs/v1-readonly-hostaway-mcp.md。