Nomad Stays

NomadStays MCP 服务

一个 MCP（Model Context Protocol） 服务，让 AI Agent 能够访问 Nomad Stays 的住宿数据——可按国家、大洲、地点、生活方式、预算、设施和空房情况进行搜索。

兼容 Claude、ChatGPT 以及任何支持 MCP 的 AI Agent。

可用工具

完整的最新工具列表共 78 个。请参阅 mcp.nomadstays.com 查看包含参数的完整参考文档——本 README 按类别列出工具；新增或更改工具时，请确保两处内容保持同步。

搜索、空房情况和参考信息（公开，无需身份验证）

工具	描述
getStaysByCountry	按 2 个字母的国家代码或国家名称搜索住宿
getStaysByContinent	按大洲搜索（欧洲、亚洲、非洲等）
getStaysByLocation	在城市、地区和地点描述中进行自由文本搜索
getStaysByLifestyle	按生活方式类别筛选（数字游民、海滩、城市等）
getStaysByBudget	按指定时长和货币查找符合预算的住宿
getStaysByAmenities	按设施筛选（WiFi、泳池、空调等）
getStaysByWiFiSpeed	按最低 WiFi 下载速度（Mbps）筛选
getStayByID	获取单个住宿的完整详情
getStayCountsByCountry	获取各国住宿数量，按数量从多到少排序（可选的大洲筛选条件）
getAllLifestyles	列出所有可用的生活方式类别
getAllAmenities	列出所有可用设施
checkStayAvailability	检查住宿在指定日期是否有空房
findNearestAvailability	在首选日期已满时，查找最近的可订日期
getAvailabilityByMonth	获取指定月份的所有可订时间段
getRoomAvailability	获取指定日期范围内每个房间的可订情况
getRoomAmenities	获取指定房间的完整设施列表，包括 WiFi 指标
searchHelpCenter	搜索 Nomad Stays 帮助中心文章
getHelpCenterArticle	按 ID 获取指定的帮助文章
listHelpCenterCategories	列出所有帮助中心类别

AI Agent 账户注册

如果你正在协助的人还没有 Nomad Stays 账户，可使用 signupNomadStaysAccount 工具为其创建账户——无需身份验证、浏览器或 CAPTCHA。

工具	描述
signupNomadStaysAccount	为尚无账户的人创建一个新的 Nomad Stays 账户。返回 pending_email_confirmation——不会返回会话或令牌。

注意：

• 账户创建后处于未激活状态，直到用户点击发送到其邮箱的确认链接——此调用不会返回会话或令牌，Agent 也无法自行登录或以该用户的身份操作。这是信任边界：它可证明请求者拥有真实的邮箱，以此代替公开浏览器注册表单所使用的 CAPTCHA／蜜罐检查。
• 服务器端限制为每个源 IP 每 5 分钟最多 2 次请求（主仓库中的 Controllers/AgentSignupApiController.cs）。
• 用户确认邮箱并通过 www.nomadstays.com/Account/Login 正常登录后，可申请 MCP bearer 令牌或完成 OAuth（参见下文“可信住宿合作伙伴管理工具”），以便今后让自己的 Agent 代表自己操作。

产品、购买和申请工具（需要 MCP Agent 令牌）

住宿、体验和共享办公申请均遵循相同的 list / get / create / save / submit 生命周期。住宿和体验申请需支付一次性 39 欧元的申请费（产品 8 和 9）；共享办公申请无需付费。

工具	描述
getProductInfo	查询产品价格和是否可购买（产品 8 = 住宿申请，产品 9 = 体验申请）
purchaseProduct	代表调用者本人发起购买；返回 checkoutUrl，或结果为“已免除费用”
getPurchaseStatus	检查购买是否已付款，并向支付服务商实时核验
listStayApplications / getStayApplication / createStayApplication / saveStayApplication / submitStayApplication	完整的住宿申请生命周期
listExperienceApplications / getExperienceApplication / createExperienceApplication / saveExperienceApplication / submitExperienceApplication	完整的体验申请生命周期（至少 4 天的体验，由服务端强制执行）
listCoworkingApplications / getCoworkingApplication / createCoworkingApplication / saveCoworkingApplication / submitCoworkingApplication	完整的共享办公申请生命周期——无需申请费

预订（需要 MCP Agent 令牌）

工具	描述
quoteStayBooking	在确认前计算意向预订的价格（套餐、日期、宾客人数）
bookStay	代表调用者本人创建预订；返回 checkoutUrl，或结果为已确认
getBookingStatus	检查预订是否已确认，并向支付服务商实时核验
listMyBookings	列出调用者本人的预订，包括任何仍待处理事项的 needsAction / checkoutUrl
createStayEnquiry	咨询目前无法预订的住宿；Nomad Stays 团队会通过电子邮件回复会员

Trusted Stay Partner 管理工具

上述工具为只读且公开（applications 除外；它们可自助使用，但仍受令牌限制）。另有一组工具，允许已授权的 Trusted Stay Partner 自己的 AI Agent读取和写入其自有房源数据——能力与其通过 Nomad Stays 管理界面使用的相同（不多不少）。这些工具需要通过合作伙伴的 Operator Information 页面 www.nomadstays.com/stayadmin/user-profile-stays 申请并签发的 bearer token（账户必须启用 2FA 才能申请），并将其设置为 NOMADSTAYS_MCP_AGENT_TOKEN。每次调用都会在服务端限定为经身份验证的账户实际拥有的 Stay。

工具	描述
getMyStays / getMyStayDetail / updateStayDetail	读取/更新 Stay 的核心详情（标题、描述、地址、政策）
getMyStayOnboardingStatus	Stay 仪表板中的六项“房源完成度”评分（Stay 详情、可订状态、客房、套餐、Wi-Fi、运营方信息）以及总体百分比——Wi-Fi 评分反映测试的新近程度，而非速度评级
getMyStayRooms / createStayRoom / updateStayRoom / deleteStayRoom	完整的客房 CRUD，包括床型尺寸、设施和照片
getRoomTypeOptions / getRoomFacilityOptions	查询有效客房类型/设施的参考选项（精品型 Stay 与标准 Stay 的选项不同）
uploadStayPhoto / getMyStayPhotos / deleteStayPhoto / reorderStayPhotos	Stay 级别的照片管理，包括重新排序
deleteRoomPhoto / reorderRoomPhotos	客房级别的照片管理
getMyStayPackages / createStayPackage / updateStayPackage / deleteStayPackage	价格套餐 CRUD——sellPrice 始终由服务端计算，不能直接设置
getCurrencyOptions / getBusinessModelOptions	查询套餐币种和业务模式的参考选项
getMyStayOrganisationalData / updateStayOrganisationalData	地址、入住/退房政策、取消政策、宠物/儿童/停车规则
getStayTypeOptions / getCountryOptions / getCancellationPolicyOptions / getAdditionalInformationOptions	查询机构数据字段的参考选项
getMyStayContacts / updateStayContacts	面向公众的联系信息
getMyStayFacilities / updateStayFacilities / getFacilityGroups	设施复选框，分组方式与管理界面完全一致
getMyBusinessProfile / updateHostBusinessProfile	商业资料（不包括个人、银行和税务字段——这些信息绝不会通过 MCP 暴露）

关键规则：精品型 Stay（客房类型为 Boutique1–Boutique6）和标准 Stay 分别进行校验——务必先调用 getRoomTypeOptions。套餐价格档位固定为 7/14/21/30 晚，无需全部设置——设置其中部分档位（例如仅设置 1 周）也是有效的。advertisingEndpoint 仅适用于采用 Advertising 业务模式的 Stay。所有工具均永久排除个人、银行和税务详情。

设置

1. 先决条件

• Node.js 20+
• 可访问 Nomad Stays SQL Server 数据库（托管于 Coolify/Hetzner）

2. 安装

git clone https://github.com/nomadstays/nomadstays-mcp-server.git
cd nomadstays-mcp-server
npm install

3. 配置

cp .env.example .env
# Edit .env and set your NOMADSTAYS_DB_CONNECTION string

4. 构建

npm run build

5. 运行（stdio 模式——适用于 Claude Desktop / 本地 MCP 客户端）

node build/index.js

6. 运行（HTTP 模式——适用于托管/远程部署）

PORT=8080 node build/index.js

HTTP 端点：

• POST /mcp — MCP Streamable HTTP 传输
• GET /health — 健康检查
• GET /api/mcp/stats/daily — 每日使用统计
• GET /api/mcp/stats/tools — 按工具统计使用情况

Claude Desktop 配置

复制 claude_desktop_config.example.json，更新路径和连接字符串，然后合并到 claude_desktop_config.json 中：

{
  "mcpServers": {
    "nomadstays": {
      "command": "node",
      "args": ["/path/to/nomadstays-mcp-server/build/index.js"],
      "env": {
        "NOMADSTAYS_DB_CONNECTION": "Server=tcp:..."
      }
    }
  }
}

部署

Nomad Stays 的生产环境将其 MCP 服务作为 Docker 容器部署在 Coolify（在 Hetzner 上自托管），而不是 Azure App Service。此仓库不包含自己的 Dockerfile——请使用标准的 Node.js 构建流程将其容器化（Node 20+、npm run build，运行 dist/index.js），并部署到任何支持 Docker 的主机；在目标平台上将 NOMADSTAYS_DB_CONNECTION（以及 HTTP 模式下的 PORT/HTTP_PORT）设为环境变量。

技术栈

• TypeScript + Node.js 20
• @modelcontextprotocol/sdk
• Express（HTTP 模式）
• mssql（SQL Server 连接）