CohostSTR (MCP server for Guesty)

CohostSTR — Guesty 的 MCP 服务

这是一个开源、支持写入的 MCP（模型上下文协议）服务，用于 Guesty 物业管理。将任意兼容 MCP 的 AI 客户端（Claude、ChatGPT、Copilot、Cline）连接到你的 Guesty 账号，即可管理预订、与房客沟通、跟踪财务状况并更新定价。

**现已上线：**全部 43 个 Guesty 工具，免费使用——涵盖预订、房源、房客、日历、房客消息、财务报告、定价和房源写入、运营、评价、webhook 以及 IoT／房源健康状况。无需许可证密钥，也没有付费层级。

**为什么选择 MCP：**Guesty 是短租领域规模较大的 PMS 平台之一，但此前没有 MCP 集成。所有主流 PMS 都需要 MCP 集成。

**已在我们自己的短租房源组合中构建并投入生产使用。**采用 Node.js + MCP SDK + Express，MIT 许可。我们总结的经验：Guesty 的 /reservations 端点只返回未来的数据（历史数据需使用日历端点），SSE 传输无法在 Vercel 无服务器环境中运行（这是预期行为）。全部 44 个工具均免费。

完整工具列表：共注册 44 个工具，全部免费——43 个 Guesty 工具（23 个只读工具、16 个写入／房客消息工具，包括 get_conversations 和 draft_guest_reply，以及 4 个 IoT／房源健康状况工具），另有 get_license_info，用于报告此服务自身的许可状态，且不会调用 Guesty API。没有付费层级。GUESTY_MCP_LICENSE_KEY 是可选项，不会改变你可以调用的工具。

**所有功能均免费。**全部 44 个工具无需许可证密钥即可使用。付费前缀密钥仍会被识别（并显示在 get_license_info 中），但并非必需，也不会解锁任何额外功能——因为没有额外功能可供解锁。你可以设置或省略 GUESTY_MCP_LICENSE_KEY；两种方式的访问权限完全相同。

快速开始

最简单的方式：用一条命令配置 Claude Desktop（密钥不会显示在屏幕上）

npx -y cohoststr-mcp setup

它会通过隐藏提示输入你的 Guesty Client ID 和 Client Secret（不会回显任何内容，连星号也不会显示），备份你现有的 Claude Desktop 配置，添加 CohostSTR，并保留你已有的其他 MCP 服务。然后退出并重新打开 Claude Desktop。当 Claude 询问是否使用会更改内容的工具时，请仅允许使用一次（不要选择“始终允许”），这样每次更改都需要你批准。

或自行配置

npx cohoststr-mcp

Claude Code：

claude mcp add cohoststr -s user -e GUESTY_CLIENT_ID=your-client-id -e GUESTY_CLIENT_SECRET=your-client-secret -- npx -y cohoststr-mcp

手动配置 Claude Desktop：依次打开 Settings > Developer > Edit Config，然后在 mcpServers 下添加：

{
  "mcpServers": {
    "cohoststr": {
      "command": "npx",
      "args": ["-y", "cohoststr-mcp"],
      "env": {
        "GUESTY_CLIENT_ID": "your-client-id",
        "GUESTY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

获取 Guesty API 凭据

需要使用支持 Open API 的 Guesty 方案（Pro 或 Enterprise；Lite 不支持，详见 guesty.com/pricing）。

1. 登录 Guesty
2. 前往 Integrations > Developer tools > OAuth applications，并创建新的 API 应用（Guesty 快速入门指南）
3. 复制你的 Client ID 和 Client Secret（Guesty 只会显示一次密钥）

全部 44 个工具

预订与房客

工具	描述
get_reservations	根据筛选条件（日期、房源、状态、房客）获取预订
create_reservation	创建直接预订（从网站同步到 Guesty）
update_reservation	更新预订状态、日期、房客信息或添加备注
search_reservations	按房客姓名、电子邮件或确认码搜索
get_reservation_financials	查看预订的详细财务明细
create_reservation_note	为预订添加内部备注
get_guests	按姓名或电子邮件搜索房客数据库
get_guest_by_id	获取详细的房客档案

房源与日历

工具	描述
get_listing	获取房源详情或列出所有房源
update_listing	更新标题、描述、便利设施、最少入住晚数、最多入住人数
get_calendar	按日期查看空房情况和价格
update_calendar	封锁／取消封锁日期，设置最少入住晚数
get_calendar_blocks	获取封锁日期及原因
get_listing_occupancy	计算指定日期范围内的入住率
get_photos	获取房源照片及说明
update_photos	替换或重新排列房源照片

消息

工具	描述
get_conversations	获取住客消息历史记录
send_guest_message	在对话中向住客发送消息

财务与定价

工具	描述
get_financials	收入、付款和佣金数据
update_pricing	更新基础价格或特定日期的价格
get_listing_pricing	获取基础价格、折扣和费用详情
update_listing_pricing	更新基础价格、清洁费和折扣
get_owner_statements	房东收入报表和报告
get_expenses	跟踪运营支出
create_expense	创建新的支出记录
get_revenue_summary	汇总所有房源的收入

运营

工具	描述
get_tasks	获取清洁和维护任务
create_task	创建清洁或维护任务
get_reviews	获取所有渠道的住客评价
respond_to_review	回复住客评价
get_channels	列出每处房源已连接的预订渠道
get_supported_languages	获取房源支持的语言

自动化与集成

工具	描述
get_automation_rules	列出自动化和工作流规则
get_webhooks	列出已注册的 Webhook
create_webhook	注册新的 Webhook 以接收事件通知
delete_webhook	移除已注册的 Webhook
get_custom_fields	获取房源或预订的自定义字段
get_account_info	获取账户信息和订阅详情

服务与许可

工具	描述
get_license_info	报告此 MCP 服务自身的许可状态——目前所有工具均免费；列出工具账目，以及是否检测到密钥。不会调用 Guesty API。

它计入已注册的 44 个工具，但不计入“43 个 Guesty 工具”，因为它报告的是我们的许可状态，而非对你的 Guesty 账户执行操作：43 个 Guesty 工具 + 此工具 = 44 个。

IoT 与房源状况

工具	描述
get_readiness_score	根据清洁、维护和 IoT 信号计算房源综合周转准备度评分
get_property_health	每处房源的综合状况信号：预订状态、未处理的维护警报、评价评分、上次清洁时间戳、IoT 集线器状态
submit_checkout_photos	接收退房后的照片上传，并将其记录到房源的维护／清洁记录中
get_maintenance_alerts	列出或筛选房源或房源组合中未处理的维护警报

这四个工具和其他所有工具一样，均可免费使用。它们读取本地 IoT 数据库（IOT_DB_PATH），该数据库由可选的 Webhook 接收器（src/webhook/iot-receiver-server.js）填充。如果没有设备报告数据，它们会返回空的设备和警报列表、指出每项缺失信号的低准备度评分，以及健康状况快照中值为 null 的 IoT 字段——这些都不是错误；Guesty 端的字段仍会正常填充。

使用场景

• 宾客沟通：宾客消息工具基于真实预订数据起草并发送回复
• 收益管理：提取财务报告、分析入住率、优化定价
• 运营：跟踪入住/退房、协调清洁安排、管理可用情况
• 营销：找出入住率较低的时段，创建有针对性的促销活动
• 互联工具：让技术栈中的每个兼容 MCP 的客户端都能访问相同的房源数据

要求

• Node.js 18+
• 拥有 API 访问权限的 Guesty 账户（Professional 套餐或更高版本）
• 兼容 MCP 的 AI 客户端（Claude Code、Cursor、Windsurf 等）

环境变量

变量	默认值	用途
GUESTY_CLIENT_ID	—	OAuth2 客户端 ID（必填）
GUESTY_CLIENT_SECRET	—	OAuth2 客户端密钥（必填）
IOT_WEBHOOK_PORT	3100	IoT webhook 接收器存根（src/webhook/iot-receiver-server.js）的端口。仅限本地/反向代理使用——请勿公开暴露。生产环境需要使用终止 TLS 并针对 IOT_WEBHOOK_SECRET 执行真实 HMAC 验证的反向代理。

API 参考

此服务封装了 Guesty Open API。身份验证使用 OAuth2 客户端凭据流程，并支持自动令牌缓存、重试逻辑和速率限制处理。

构建者

由一位短期租赁经营者基于自己的房源组合构建并运行，并与 STR 社区分享。与 Guesty 无关联。

许可证

MIT