关于 Hotel & Vacation Rental MCP - live prices & reviews across Booking, Airbnb, Vrbo & Google Hotels
StayingAPI 的 Hotel & Vacation Rental MCP 服务可跨 Booking.com、Airbnb、Vrbo 和 Google Hotels 搜索住宿、可订情况、价格及评价。七个只读工具以统一格式返回数据,并支持跨平台比价。
主要功能
- 01跨四个平台搜索住宿
- 02逐日检查可订情况
- 03跨平台比较价格
- 04获取房源详情和评价
- 05统一住宿数据格式
适用场景
- 01按地点和日期查找住宿
- 02比较同一房源在各网站的价格
- 03检查每日可订情况和最少入住晚数
- 04汇总住宿评价
MCP 相关
通过托管的 Streamable HTTP MCP 服务提供七个只读工具。客户端通过 OAuth 2.1 验证身份;工具支持搜索、检查可订情况、比价、获取评价和轮询任务。
配置
远程服务无需本地安装。选择你使用的客户端,复制配置或使用一键安装。
https://mcp.stayingapi.com/mcpclaude mcp add --transport http com-stayingapi-hotel-vacation-rental https://mcp.stayingapi.com/mcp{"mcpServers":{"com-stayingapi-hotel-vacation-rental":{"type":"http","url":"https://mcp.stayingapi.com/mcp"}}}在 Cursor 中打开{"servers":{"com-stayingapi-hotel-vacation-rental":{"type":"http","url":"https://mcp.stayingapi.com/mcp"}}}在 VS Code 中打开{"mcpServers":{"com-stayingapi-hotel-vacation-rental":{"type":"http","url":"https://mcp.stayingapi.com/mcp"}}}{"mcpServers":{"com-stayingapi-hotel-vacation-rental":{"serverUrl":"https://mcp.stayingapi.com/mcp"}}}命令在终端中运行;JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。
工具
详细介绍
酒店与度假租赁 MCP——提供 Booking.com、Airbnb、Vrbo 和 Google Hotels 上的实时价格、房态与评价
只需向 AI 提问,即可搜索住宿、比较 Booking.com、Airbnb、Vrbo 和 Google Hotels 上的价格,并获取评价。一个托管式 MCP,注册即享 300 点免费额度,无需银行卡。
七个只读工具——搜索、房态、房源详情、价格、跨 OTA 价格比较、评价和任务轮询——适用于 Claude、ChatGPT、Cursor、Claude Code 及任何 MCP 客户端。
4 个预订平台,一套架构 · 7 个只读工具 · 跨 OTA 价格比较 · OAuth 2.1,无需将密钥粘贴到 Agent 中 · 注册即享 300 点免费额度,无需银行卡 StayingAPI 是一家独立的住宿数据服务。StayingAPI 与 Airbnb、Booking.com、Vrbo 或 Google Hotels 均无关联,也未获得其认可或赞助。这些名称均为其各自所有者的商标,此处仅用于说明 StayingAPI 的 API 和 MCP 服务可查询的数据来源。
一行安装
Claude Code
claude mcp add --transport http stayingapi https://mcp.stayingapi.com/mcp
Claude Desktop、ChatGPT、Cursor 或其他任何 MCP 客户端——将其添加为 Streamable HTTP 服务:
https://mcp.stayingapi.com/mcp
无需粘贴 API 密钥:首次调用时会打开 OAuth 登录页面(免费账户、300 点额度,无需银行卡)。各客户端的具体步骤请参阅快速安装,整个仓库也可作为Agent 插件安装。
为什么选择 Hotel & Vacation Rental MCP
你已经在手动比较四个网站上的住宿:Booking.com 上的酒店、Airbnb 上的公寓、Vrbo 上的别墅,以及用于核对价格的 Google Hotels。每个平台都有不同的页面、不同的评分标准,而且没有一个提供可以直接注册使用的 API。
连接一次,之后只需提问。 将此 MCP 服务添加到 Claude、ChatGPT、Cursor 或任何 MCP 客户端,只需设置一次,你的 AI 助手就能在对话中搜索真实住宿、查询所选日期的实际价格、比较同一房源在不同预订网站上的价格,并阅读标准化评价——无需编写代码,也无需重复设置。
所有结果都会返回统一的架构。酒店客房和度假别墅会返回相同结构的对象;评分会保留各自原生的评分标准,而不是被悄悄换算;跨 OTA 比价会返回每个网站的报价,以及计算得出的最低价和中位价,因此你无需自己重新计算。
快速体验:
Find 2-bed stays in Lisbon for these dates under EUR 150,
compare the top one's price across Airbnb, Booking.com and Vrbo,
and summarize its reviews.
只需一个提示词,就能调用三个工具——search_stays、compare_prices、get_reviews——而无需编写任何代码。
安装为 Agent 插件 · 最简单
此代码库根目录是符合规范的 Agent Plugins 1.0.0 软件包——这是于 2026-08-06 发布的可移植格式,ChatGPT、Codex、Cursor、GitHub Copilot、Kiro 和 VS Code 均支持该格式。安装一次,即可获得 MCP 服务以及内置的 stays 技能。该技能会教你的 Agent 哪个工具适合回答哪个问题、如何以较低成本并行查询多个平台,以及 Airbnb/Vrbo 使用 5 分制评分,而 Booking.com 使用 10 分制——避免将 9 分与 4.5 分直接比较。
plugin.json # Agent Plugins 1.0.0 manifest
mcp.json # hosted MCP server, streamable-http, OAuth (no keys)
skills/stays/SKILL.md # when + how to use the 7 read-only tools
.cursor-plugin/plugin.json # Cursor plugin manifest, same MCP + skill (+ marketplace.json)
VS Code — 打开命令面板 → Chat: Install Plugin From Source,然后粘贴:
https://github.com/stayingapi/hotel-vacation-rental-mcp
或者在 settings.json 中注册本地克隆:
"chat.pluginLocations": { "/absolute/path/to/hotel-vacation-rental-mcp": true }
Cursor — 在侧边栏中选择 Customize → 找到该插件 → Install。要安装本地克隆:
git clone https://github.com/stayingapi/hotel-vacation-rental-mcp ~/.cursor/plugins/local/stayingapi
然后选择 Developer: Reload Window。
添加到 Cursor — 仅安装 MCP 服务,无需克隆。将此深层链接粘贴到浏览器中:
cursor://anysphere.cursor-deeplink/mcp/install?name=stayingapi&config=eyJ1cmwiOiJodHRwczovL21jcC5zdGF5aW5nYXBpLmNvbS9tY3AifQ==
ChatGPT、Codex、GitHub Copilot、Kiro 及其他客户端 — 将客户端的插件机制指向此代码库或本地克隆。Agent Plugins 1.0.0 标准化的是软件包格式,而非安装流程,因此每个客户端都有自己的安装流程。
30 秒示例
Find a 2-bedroom apartment in Split, Croatia for 12-15 June, 2 adults, under EUR 150 a night.
一次 search_stays 调用即可将 Airbnb、Booking.com、Vrbo 和 Google Hotels 的结果合并为一个标准化列表,每项都附有预订 URL。无需配置 API 密钥——首次调用时会打开 OAuth 登录页面(免费账户提供 300 个点数,无需信用卡)。然后还可以继续追问,而这些操作通常需要打开二十个浏览器标签页:
Is that one cheaper on Booking or Airbnb? → compare_prices (one call, every OTA)
Is it free all week, and what's the min stay? → check_availability (day by day)
全部七个工具均为只读——无法通过这里预订、取消或更改预订。
此软件包不包含任何凭据——Agent Plugins 1.0.0 禁止嵌入机密信息,授权由客户端管理。你可以自行验证此软件包:
curl -sO https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
curl -sO https://agent-plugins.org/schemas/1.0.0/mcp.schema.json
npx ajv-cli@5 validate --spec=draft2020 -s plugin.schema.json -d plugin.json
npx ajv-cli@5 validate --spec=draft2020 -s mcp.schema.json -d mcp.json
快速安装
要求:
建议:添加规则,让 AI 自动调用它
将以下内容粘贴到客户端的自定义指令或规则文件中:
When I mention a hotel, an Airbnb/Booking.com/Vrbo/Google Hotels listing, a place to stay, travel dates, or ask to compare accommodation prices or read stay reviews, automatically use the StayingAPI MCP tools to fetch real data before answering.
服务 URL: https://mcp.stayingapi.com/mcp(Streamable HTTP 传输)
在 Claude 中安装(桌面版和 Web 版)——推荐
设置 → 连接器 → 添加自定义连接器 → 粘贴:
https://mcp.stayingapi.com/mcp
Claude 会在浏览器弹窗中为你完成 OAuth 2.1 登录,将连接器关联到你的 StayingAPI 账户及其额度余额——**无需 API 密钥。**随后,工具列表中会显示这七个只读工具。
更喜欢使用桌面版配置文件?将以下内容添加到 claude_desktop_config.json:
{
"mcpServers": {
"stayingapi": {
"url": "https://mcp.stayingapi.com/mcp"
}
}
}
在 Claude Code 中安装(命令行)
OAuth(推荐):
claude mcp add --transport http stayingapi https://mcp.stayingapi.com/mcp
然后在 Claude Code 中运行 /mcp,并完成 OAuth 提示中的操作。
在无头环境中运行,或想改用密钥?MCP 服务仅接受 OAuth 登录,因此脚本和后端请使用 REST API 和 stay_live_ 密钥。
在 ChatGPT 中安装
- 启用开发者模式:设置 → 应用和连接器 → 高级设置。
- 前往设置 → 连接器 → 添加 MCP 服务(在连接器面板中创建)。
- 粘贴服务 URL:
https://mcp.stayingapi.com/mcp
- 根据提示完成 OAuth 登录——无需 API 密钥。
在 Cursor 中安装(一键或手动)
**一键安装:**使用本 README 顶部的在 Cursor 中安装徽章。
**手动安装:**添加到 ~/.cursor/mcp.json(全局)或 .cursor/mcp.json(单个项目):
{
"mcpServers": {
"stayingapi": {
"url": "https://mcp.stayingapi.com/mcp"
}
}
}
首次调用工具时会打开 OAuth 登录。MCP 服务不提供 API 密钥选项。
其他 MCP 客户端
将 https://mcp.stayingapi.com/mcp 添加为 Streamable HTTP MCP 服务。
- 身份验证采用 OAuth 2.1 + PKCE 和动态客户端注册:支持该功能的客户端会自动完成身份验证,无需进行任何配置。
- MCP 服务不接受 API 密钥。不支持 MCP OAuth 的客户端无法连接;请改用
stay_live_密钥调用 REST API。
上方只列出了已通过 stayingapi.com/docs/mcp 验证的格式。如果你的客户端不在列表中,通用的 Streamable HTTP 配置就是全部所需配置。
身份验证
MCP 服务和 REST API 最终使用同一账户和同一额度余额,但登录方式不同:
- MCP 服务:仅支持 OAuth 2.1 + PKCE (S256) 和动态客户端注册。 你只需在浏览器弹出窗口中授权一次,即可将连接器关联到你的 StayingAPI 账户。支持 DCR 的客户端会自动发现所有信息,因此无需将密钥粘贴到 Agent 中。MCP 服务不接受 API 密钥,MCP 工具调用实时执行。
- REST API:使用持有者 API 密钥。 适用于脚本、后端和流水线。密钥格式为
stay_live_...(实际调用实时数据源)或stay_test_...(确定性的沙盒固定数据,始终为 0 个额度)。发送至https://api.stayingapi.com/v1时,请使用Authorization: Bearer stay_live_...。
共用一个余额,速率限制分开计算。 MCP 调用与 REST 密钥共用同一额度余额。REST 按密钥实施速率限制;MCP 按用户实施速率限制——速率限制桶彼此独立,但使用同一个钱包。
安全提示: 请像对待密码一样保护
stay_live_密钥。新密钥的密钥值只会显示一次,且仅以 SHA-256 哈希形式存储,因此无法找回。切勿将密钥提交到代码仓库或粘贴到共享配置中;如果密钥泄露,请在控制面板中撤销并重新生成。
可用工具
全部七个工具均为只读(标注为 readOnlyHint: true、idempotentHint: true)。没有写入工具,因此无法通过这里进行预订、取消或更改。每个工具都与一个 REST 端点一一对应,运行相同的验证和缓存流程,并返回相同的统一 { data, meta } 封装。
1. search_stays
按地点、日期、入住人数和筛选条件搜索多个平台上的房源,并合并到同一套架构中。这是覆盖面最广的端点,也是「一套架构,适用于所有平台」的最佳示例。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
location | string | 是 | 地点名称(Split, HR)或 lat,lng |
checkIn / checkOut | date | 否 | YYYY-MM-DD;必须同时提供;日期不能在过去 |
adults / children / childAges[] / rooms | integer | 否 | childAges[] 的长度必须等于 children |
propertyType[] | enum[] | 否 | hotel | apartment | house | villa | cottage | other |
amenities[] | enum[] | 否 | 标准化设施分类体系 |
minBedrooms / priceMin / priceMax / minGuestRating | number | 否 | 在标准化后应用筛选条件 |
platforms[] | enum[] | 否 | airbnb | booking | vrbo | google;决定扇出范围 |
limit / cursor / sort / currency | mixed | 否 | limit 为 1-40;sort = recommended | price_asc | price_desc | rating_desc |
响应(精简版):
{
"data": [
{
"id": "stays_booking_abramovic2",
"platform": "booking",
"platformListingId": "abramovic2",
"url": "https://www.booking.com/hotel/hr/abramovic2.html",
"name": "Apartments Abramović",
"propertyType": "apartment",
"location": { "lat": 43.51, "lng": 16.44, "city": "Split", "country": "HR" },
"starRating": null,
"guestRating": 9.1, "ratingScale": 10, "reviewCount": 142,
"maxOccupancy": 4, "bedrooms": 2, "bathrooms": 1,
"amenities": ["pool", "kitchen", "air_conditioning", "wifi"],
"host": { "name": "Marko", "isSuperhost": false },
"price": { "currency": "USD", "nightlyPrice": 303, "totalPrice": 2122, "nights": 7 }
}
],
"meta": {
"platforms": ["airbnb", "booking"],
"cached": false, "partial": false, "currency": "USD",
"pagination": { "limit": 20, "cursor": null, "nextCursor": "eyJ…", "hasMore": true },
"platformResults": [
{ "platform": "airbnb", "status": "ok", "cached": false, "count": 18 },
{ "platform": "booking", "status": "ok", "cached": true, "count": 20 }
],
"warnings": []
}
}
2. check_availability
查询某个平台上一个已知房源(或一批房源)在指定日期范围内逐日的可订情况。每一天都会报告是否可订、最少入住晚数要求,以及是否允许入住、退房和预订。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
platform | enum | 是 | 单个平台;不支持扇出 |
listingId / listingIds[] / url | string | 三选一 | 房源 ID、多个房源 ID,或完整的房源 URL |
startDate / endDate | date | 是 | 日期不能在过去;时间范围最长为 365 天 |
onlyAvailable | boolean | 否 | 如果为 true,则只返回可预订的日期 |
响应(精简版):
{
"data": [
{
"platform": "airbnb",
"listingId": "42307961",
"dates": [
{ "date": "2026-07-13", "available": true, "minNights": 7, "checkIn": true, "checkOut": false, "bookable": true },
{ "date": "2026-07-14", "available": true, "minNights": 7, "checkIn": false, "checkOut": false, "bookable": true }
]
}
],
"meta": { "platforms": ["airbnb"], "cached": false, "partial": false, "warnings": [] }
}
3. get_listing
单个房源的完整规范化详情:按规范分类法整理的便利设施、照片、房东、地理位置、评分,以及在传入日期时附带的实时价格。详情缓存 24 h,任何附带的价格则按 1 h 的价格 TTL 缓存;数据在读取时组合,因此过期价格不会随新鲜详情一起返回。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
platform | 枚举 | 是 | vrbo | booking | airbnb | google |
id | 字符串 | 是 | 平台原生房源 ID,须与来源中的值完全一致 |
checkIn / checkOut | 日期 | 否 | 传入后会附带尽力获取的实时价格 |
adults / children / childAges[] / currency | 混合 | 否 | 仅与日期搭配使用 |
响应(经删减):
{
"data": {
"id": "stays_booking_abramovic2",
"platform": "booking",
"platformListingId": "abramovic2",
"name": "Apartments Abramović",
"propertyType": "apartment",
"location": { "lat": 43.51, "lng": 16.44, "city": "Split", "country": "HR" },
"guestRating": 9.1, "ratingScale": 10, "reviewCount": 142,
"maxOccupancy": 4, "bedrooms": 2, "bathrooms": 1,
"amenities": ["pool", "kitchen", "air_conditioning", "wifi"],
"images": ["https://…"],
"host": { "name": "Marko", "isSuperhost": false },
"price": { "currency": "USD", "nightlyPrice": 303, "totalPrice": 2122, "nights": 7 }
},
"meta": { "platforms": ["booking"], "cached": false, "partial": false, "warnings": [] }
}
4. get_price
针对单个房源、指定日期和入住人数获取真实报价。传入 search_stays 返回的平台原生 ID(Airbnb 和 Vrbo 使用数字 ID,Booking.com 和 Google Hotels 使用 slug 字符串),或完整房源 URL。响应始终为真实数值价格或类型化错误——绝不会返回其他房源的价格。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
platform | 枚举 | 是 | vrbo | booking | airbnb | google |
listingId | 字符串 | 是 | search_stays.platformListingId 中的平台原生 ID,或传入 url |
checkIn / checkOut | 日期 | 是 | YYYY-MM-DD;checkOut 必须晚于 checkIn |
adults / children / childAges[] / currency | 混合 | 否 | ISO-4217 货币代码,会原样传递并在响应中回显 |
响应(经删减):
{
"data": {
"platform": "booking",
"listingId": "abramovic2",
"currency": "EUR",
"nightlyPrice": 303,
"totalPrice": 2122,
"fees": { "cleaning": null, "service": null, "taxes": null },
"nights": 7,
"occupancy": { "adults": 2, "children": 2, "childAges": [8, 13] },
"source": "booking",
"url": "https://www.booking.com/hotel/hr/abramovic2.html"
},
"meta": { "platforms": ["booking"], "cached": false, "partial": false, "warnings": [] }
}
5. compare_prices
旗舰工具。 通过 Google Hotels 骨干服务解析房源,一次调用即可比较该房源在多个预订网站上的价格。响应包含各网站的报价,以及 StayingAPI 计算的 min 和 median 一等字段,因此无需重新计算,即可获取跨网站的最低价和典型价格。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name / googleHotelId / location | 字符串 | 三选一 | 用于解析的房源名称、准确的 Google Hotels ID,或用于消除歧义的地点 |
checkIn / checkOut | 日期 | 是 | YYYY-MM-DD;不得早于当前日期 |
adults / children / childAges[] / currency | 混合 | 否 | ISO-4217 货币代码,会原样传递并在响应中回显 |
响应(经删减):
{
"data": {
"property": "Hotel X, Sibenik",
"checkIn": "2026-07-13",
"checkOut": "2026-07-20",
"currency": "EUR",
"min": 2122,
"median": 2151,
"offers": [
{ "ota": "booking.com", "totalPrice": 2122, "currency": "EUR", "url": "https://…" },
{ "ota": "expedia", "totalPrice": 2180, "currency": "EUR", "url": "https://…" }
]
},
"meta": { "platforms": ["google"], "cached": false, "partial": false, "warnings": [] }
}
6. get_reviews
获取单个平台上单个房源的规范化分页评价。保留原生评分制,并在每条评分旁回显(Airbnb、Vrbo 和 TripAdvisor 使用 5 分制;Booking.com、Expedia 和 Hotels.com 使用 10 分制),绝不会在不提示的情况下重新换算,因此不会误将 9 分与 4.5 分进行比较。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
platform | 枚举 | 是 | 平台枚举值 |
listingId / url | 字符串 | 二选一 | 该平台上的房源 ID,或完整房源 URL |
limit / cursor | 混合 | 否 | limit 为 1-100;不透明的 base64 游标 |
language / minRating / sort | 混合 | 否 | ISO-639-1 语言筛选;sort = recent | rating_desc | rating_asc |
响应(经删减):
{
"data": [
{
"platform": "booking",
"listingId": "abramovic2",
"reviewId": "r987",
"rating": 9, "ratingScale": 10,
"title": "Perfect family stay",
"text": "Spotless apartment a short walk from the old town…",
"author": "Jane D.", "date": "2026-05-10", "tripType": "family",
"language": "en", "ownerResponse": "Thank you!",
"liked": "Location and cleanliness", "disliked": null
}
],
"meta": {
"platforms": ["booking"], "cached": false, "partial": false,
"pagination": { "limit": 20, "cursor": null, "nextCursor": "eyJ…", "hasMore": true },
"warnings": []
}
}
7. get_job
轮询以异步作业形式返回的长时间运行的抓取任务。如果预计请求运行时间超过约 8 秒,则会返回作业句柄;Agent 调用 get_job,直到 status 为 completed 或 failed。轮询始终不消耗积分——底层工作仅在成功完成时计费一次。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
jobId | 字符串 | 是 | 原始调用返回的句柄。结果保留 24 h |
运行期间及完成后的响应(经删减):
// While running - polling is free
{
"data": { "jobId": "job_3kf…", "status": "running", "pollUrl": "/v1/jobs/job_3kf…", "estimatedSeconds": 12 },
"meta": { "creditsCharged": 0, "platforms": ["vrbo"] }
}
// On success - the payload arrives in data.result, in the same unified schema
{
"data": { "jobId": "job_3kf…", "status": "completed", "result": [ /* the endpoint's payload */ ] },
"meta": {
"platforms": ["vrbo"], "currency": "USD",
"platformResults": [ { "platform": "vrbo", "status": "ok", "cached": false, "count": 15 } ],
"warnings": []
}
}
失败的作业仍会成功返回,status: "failed",失败原因嵌套在 data.error 中(一个 { type, code, message, retryable } 对象)。失败的工作不收费。
您获取的数据
每次调用都会返回相同的统一 { data, meta } 信封,无论房源是酒店还是度假屋:
| 字段组 | 示例 |
|---|---|
| 身份信息 | id、platform、platformListingId、房源规范 url |
| 核心信息 | 房源类型、卧室数、浴室数、最大入住人数、地理位置(lat/lng/城市/国家) |
| 评分 | guestRating,带有明确的 ratingScale(5 或 10,不会在不告知的情况下重新换算)、reviewCount、starRating |
| 设施 | 覆盖四个平台的规范分类体系(pool、kitchen、air_conditioning、wifi 等) |
| 价格 | nightlyPrice、totalPrice、nights、currency,以及 fees 细分(清洁费、服务费、税费) |
| 跨平台比较 | 各网站的 offers[],以及由 StayingAPI 计算的 min 和 median |
| 可订状态 | 逐日的 available、minNights、checkIn、checkOut、bookable |
| 评价 | 原生量表评分、标题、文本、作者、日期、行程类型、语言、房东回复、喜欢/不喜欢 |
| 房东与媒体 | 房东姓名、超赞房东标记、全分辨率照片 URL |
| 调用元数据 | requestId、各平台状态、缓存标记、分页游标、警告 |
覆盖范围: Booking.com、Airbnb、Vrbo 和 Google Hotels——酒店与短租住宿使用同一套架构,一次集成即可覆盖住宿地图的两大领域。
使用场景与提示词
| 使用场景 | 示例提示词 |
|---|---|
| 行程规划 | “查找里斯本 5 月 12 日至 19 日的住宿,需有 2 间卧室、每晚低于 EUR 150,配备厨房和空调,并按住客评分排序。” |
| 跨网站价格套利 | “这家位于斯普利特的酒店,7 月 13 日至 20 日、2 位成人入住:Booking.com 和其他网站分别多少钱?最低价比中位数低多少?” |
| 评价摘要 | “提取该房源最近 50 条评价,告诉我反复出现的三项投诉,以及房东是否会回复。” |
| 查询可订状态 | “这栋 Vrbo 别墅 8 月是否有任意连续 7 晚可订?最短入住时间是多少?” |
| 家庭适住性 | “日期相同,2 位成人和 2 个分别为 8 岁和 13 岁的孩子——这三个地方中,哪些确实能住下我们所有人?含费用的总价是多少?” |
| 市场扫描 | “扫描斯普利特 7 月第一周的公寓——典型每晚价格是多少?我的房源与之相比如何?” |
| 价格一致性检查 | “比较这五家酒店在各预订网站的价格,并标记出价格偏离中位数超过 10% 的网站。” |
定价
| 入门赠送额度 | 注册即送 300 个免费额度,无需银行卡 |
| 沙盒(REST API) | stay_test_ 密钥会返回确定性测试数据,永远不消耗额度。MCP 工具调用使用实时数据 |
| 失败调用 | 失败、无结果、被拦截和未找到的调用永远不会计费——creditsCharged 为 0 |
| 异步轮询 | get_job 轮询始终不消耗额度;任务成功后只计费一次 |
| 付费套餐 | 基于额度计费。当前每次调用的成本和套餐价格:stayingapi.com/pricing |
本 README 按设计不列出付费价格,因此不会与实时定价页面不一致。MCP 和 REST 使用同一份额度余额——没有单独的 MCP 钱包或 MCP 定价。
故障排查
先根据 error.type(错误类别,与 HTTP 状态码一一对应)分支处理,再根据 error.code(稳定且更细粒度的原因)分支处理。每个错误还包含 requestId、retryable 标记和 docUrl。
401 authentication_error - 缺少凭据或凭据无效
代码:missing_api_key、invalid_api_key、revoked_api_key。
- MCP:移除连接器后重新添加,以重新授权。MCP 服务仅接受 OAuth 登录,因此粘贴的 API 密钥始终会被拒绝。
- REST API:检查密钥是否以
stay_live_或stay_test_开头、复制时是否带入了多余空格,以及它是否已在控制面板中被撤销(被撤销的密钥会立即返回revoked_api_key)。 - 验证会在校验、计费或任何上游操作之前进行,因此 401 绝不会计费。
403 permission_denied - 通常是电子邮件验证问题
代码:email_unverified、scope_insufficient、subscription_required。
email_unverified最常见:确认账户电子邮件之前,实时额度会被锁定。使用 REST API 时,你的stay_test_沙盒密钥不受影响,仍会免费返回完整测试数据,因此你可以在验证前进行端到端构建。subscription_required表示在没有有效付费订阅的情况下尝试充值——充值是订阅用户的附加服务。
402 insufficient_credits
代码:credit_balance_too_low。余额低于此次调用所需的费用。请通过程序查询,而不是猜测——账户端点会返回 credits.balance、plan、密钥 env 以及你的 rateLimit.requestsPerMinute。请在 stayingapi.com/pricing 充值或升级。
400 invalid_request - 请求本身有误
最常见的代码:missing_parameter、invalid_date_range(checkOut 必须严格晚于 checkIn)、date_in_past(按 UTC 判断)、child_ages_mismatch(childAges[] 的长度必须等于 children)、window_too_long(可用性查询窗口最长为 365 天)、invalid_cursor、limit_out_of_range、mutually_exclusive_params(你同时传入了 listingId 和 url,或两者都未传入)、needs_country。
needs_country 值得特别说明:将未经限定的 Booking.com slug 传给 get_listing 会产生歧义,因为 Booking.com slug 并非全球唯一——同一个 slug 在每个国家都可能存在。请传入国家/地区,或传入完整的房源 URL。
404 not_found - 包括有意返回的情况
代码:listing_not_found、job_not_found、identity_mismatch。
identity_mismatch 是有意设计的:解析出的房源规范身份与请求内容不匹配,因此 StayingAPI 会拒绝返回其他房源,而不是提供看似合理的错误数据。任务过期(结果保留 24 h)或任务属于其他账户时,也会返回 job_not_found——任务 ID 不是访问凭证。
429 rate_limited
代码:rate_limit_exceeded。可以重试——请遵循 Retry-After 标头,不要连续紧密重试。MCP 按用户限流,REST 按密钥限流:限流计数分别计算,但共用一个额度余额。
503 / 504 上游问题
upstream_unavailable(all_actors_failed、actor_blocked)表示所有主要和备用来源均失败或被拦截;upstream_timeout 表示同步上游操作超出了请求时限。两者都可以通过退避重试,且均不消耗额度。对于耗时较长的抓取任务,请使用异步路径:获取任务句柄,然后通过 get_job 轮询。
OAuth 无法连接
- 确认弹出窗口拦截器没有阻止登录窗口,然后清除 Cookie 并重试连接器授权。
- OAuth 发现流程从服务器的 401 响应开始。如果客户端完全无法连接,请确认它支持带动态客户端注册的 MCP OAuth 2.1。MCP 服务没有 API 密钥备用方案;若不支持 OAuth,请使用带有
stay_live_密钥的 REST API。
任务卡住了,或显示“已完成”但结果为空
`estimatedSeconds` 是预估值,并非保证——任务通常会在几十秒内完成,但在较慢的平台上可能超过 240 秒,因此请按分钟预留时间。**失败**的任务仍会返回 HTTP 200,状态为 `status: "failed"`,失败原因位于 `data.error`,而非顶层错误封装中,因此请根据 `data.status === "failed"` 进行分支处理。已完成的任务会携带 `meta.pagination: null`——游标分页仅适用于同步返回的列表响应。也可用作 REST API
您要构建的是应用或后端,而不是 Agent?同一数据也以纯 JSON REST 服务的形式提供。
| MCP | REST API | |
|---|---|---|
| 适用场景 | AI 助手和 Agent | 应用、后端、流水线 |
| 设置 | 添加 URL,授权一次 | Bearer 密钥,代码集成 |
| 身份验证 | OAuth 2.1 + PKCE(Agent 中无需密钥) | Authorization: Bearer stay_live_... |
| 速率限制 | 按用户 | 按密钥 |
| 额度 | 共用同一余额 | 共用同一余额 |
| 架构 | 相同的统一架构 | 相同的统一架构 |
| 快速入门 | 本 README | 快速入门 · API 参考 · OpenAPI |
基础 URL:https://api.stayingapi.com/v1。七个 MCP 工具与 /v1/search、/v1/availability、/v1/listing/{platform}/{id}、/v1/price、/v1/price-compare、/v1/reviews 和 /v1/jobs/{jobId} 一一对应。
联系方式
- 网站: stayingapi.com
- MCP 指南: stayingapi.com/docs/mcp
- 文档: stayingapi.com/docs · OpenAPI: api.stayingapi.com/openapi.json
- 工作流与教程: stayingapi.com/workflows
- 状态: status.stayingapi.com
- 联系: [email protected]
- 收录于: awesome-agent-plugins,一个收录基于开放标准构建的、经过验证的 Agent 插件的目录,由同一团队维护
相关代码库——属于 StayingAPI 开放资源集:hotel-api · airbnb-api · booking-com-api · vrbo-api · google-hotels-api · travel-api · travel-workflows · travel-skills
MCP 注册表
已发布到官方 Model Context Protocol 注册表,名称如下:
com.stayingapi/hotel-vacation-rental-mcp
本代码库中的注册清单:server.json(MCP 注册表) · smithery.yaml(Smithery) · glama.json(Glama)。
常见问题
2026 年有 Airbnb 或 Booking.com API 吗?
目前没有可以直接注册并立即使用的 API。Airbnb 没有开放的公共 API——访问权限通过其合作伙伴计划提供,面向获批的软件合作伙伴和物业管理系统,而非普通开发者。Booking.com 的 Demand API 也类似:需要签订合作伙伴或联盟协议,并经过审批流程才能获得凭据。Vrbo 属于 Expedia Group 的合作伙伴 API 计划,而 Google Hotels 数据则通过酒店合作伙伴数据源提供,并没有自助式开发者 API。正因如此,“airbnb api” 成了旅游科技领域搜索量最高、服务最不足的查询之一。StayingAPI 提供自助式替代方案:注册后即可获取含 300 个免费额度且无需绑定银行卡的密钥,并通过一个 REST API 或此 MCP 服务查询四个来源的住宿数据;所有响应都会统一为相同架构。
酒店或住宿 MCP 是什么?
酒店或住宿 MCP 是一种 Model Context Protocol 服务,它将住宿数据作为 AI Agent 可直接调用的工具提供:搜索住宿、逐日检查空房情况、获取完整房源详情、查询指定日期的实时报价、比较不同预订网站上的价格,以及读取经过规范化的评价。助手不再需要你把搜索结果复制到聊天中,而是会在对话过程中获取实时数据并进行推理,因此它可以自行串联步骤:先搜索,再为最佳候选项查询价格,最后总结评价。此服务托管于 https://mcp.stayingapi.com/mcp,使用 Streamable HTTP 传输,并通过统一的架构提供七种只读工具,覆盖 Booking.com、Airbnb、Vrbo 和 Google Hotels。它适用于 Claude、ChatGPT、Cursor、Claude Code 及其他 MCP 客户端,并通过 OAuth 2.1 进行身份验证,因此无需将 API 密钥粘贴到 Agent 中,而且此处的任何操作都无法预订、取消或更改预订。
StayingAPI REST API 与此 MCP 服务有什么区别? 它们是同一服务的两种入口,并非两种产品。REST API 面向应用、后端和数据管道:你发送 bearer 密钥,获取 JSON,并自行控制调用流程。MCP 服务面向 AI 助手和 Agent:添加一个 URL,通过 OAuth 2.1 授权一次,模型就可以自行调用这七种工具。底层完全相同——相同的验证、适配器和缓存流程、统一架构、错误分类,以及同一个额度余额。没有单独的 MCP 钱包或 MCP 定价。唯一真正的区别在于速率限制:REST 按密钥计量,MCP 按用户计量。编写代码时选择 REST,使用模型时选择 MCP。
这与单平台 API 或爬虫有什么不同?
单平台 API 只提供一个来源的数据,因此无法回答跨平台问题(“这栋别墅在 Booking.com 上更便宜,还是在 Vrbo 上更便宜?”)。SERP 爬虫会提供原始网页快照,需要你自行解析和规范化,既没有评分标准,也没有规范的设施分类体系,更无法保证解析出的条目就是你要查询的房源。此服务以一种架构返回四个来源的数据,明确保留各平台原生的评分标准,而不是悄悄重新换算;还提供 compare_prices,返回各网站的报价以及计算得出的最低价和中位数。如果房源的规范身份与查询目标不匹配,它也不会猜测,而是返回 identity_mismatch 错误,而非看似合理但实际错误的房源。失败、无结果和被拦截的调用绝不会计费。
如何使用 AI 比较 Booking.com、Airbnb 和 Vrbo 上的酒店价格?
将此 MCP 服务连接到你的助手,然后用自然语言提问:“比较这家酒店 7 月 13 日至 20 日在各预订网站上的价格。”模型会使用房源名称和日期调用 compare_prices。返回结果包含各网站按你选择的货币计算的总价,以及 StayingAPI 计算的 min 和 median 字段,因此助手不仅能告诉你哪个报价最低,还能说明它比通常价格低多少。对于同一处实际房源以不同名称发布在多个网站上的短租住宿,通常的流程是先用 search_stays 查找候选房源,再针对每个平台使用 get_price,按指定日期和入住人数获取准确报价。按照 Quick Install 中的说明添加自动调用规则后,每当你提到住宿,助手都会自行调用这些工具。
AI Agent 能搜索度假租赁和短期租赁,而不只是酒店吗?
可以,而且这是有意为之——这正是它既支持酒店也支持度假租赁的原因。酒店数据来自 Google Hotels 和 Booking.com;短期租赁数据来自 Airbnb 和 Vrbo。关键在于,它们返回的对象结构相同:市中心的酒店客房和乡村度假别墅都会返回房源类型、卧室数、浴室数、最多入住人数、标准化的设施列表、注明明确评分量表的住客评分,以及包含费用明细的价格。因此,Agent 可以一次性回答“斯普利特附近能住 4 人且带泳池的房源,酒店或公寓都行,哪个便宜选哪个”,而不必运行两套集成再整合结果。search_stays 接受 platforms[] 筛选条件和 propertyType[] 筛选条件,因此你可以只筛选租赁房源、只筛选酒店,或让两者参与比较。
会返回哪些数据?
每个工具都会返回相同的 { data, meta } 封装结构。房源记录包含身份信息(平台、平台原生房源 ID、标准 URL)、核心信息(房源类型、卧室数、浴室数、最多入住人数、地理位置)、注明明确 ratingScale 的住客评分,避免把 9 分制评分误认为 5 分制的 4.5 分、统一整合四个平台的标准化设施列表、房东详情、原始分辨率的照片 URL,以及包含每晚价格、总价、晚数和费用明细的定价信息。可订状态会按天返回 available、minNights、checkIn、checkOut 和 bookable。评价会返回原生量表上的评分、标题、正文、作者、日期、旅行类型、语言、房东回复,以及喜欢和不喜欢的方面。meta 区块始终会报告请求 ID、各平台状态和缓存标记、分页游标以及任何警告,让你能判断结果是部分数据还是完整数据。
如何将它添加到 Claude、ChatGPT 或 Cursor?
Claude Desktop 和 Claude Web:依次选择 Settings、Connectors、Add custom connector,然后粘贴 https://mcp.stayingapi.com/mcp 并完成 OAuth 弹窗。Claude Code:运行 claude mcp add --transport http stayingapi https://mcp.stayingapi.com/mcp,然后运行 /mcp 并授权。ChatGPT:在 Settings、Apps & Connectors、Advanced settings 下启用 Developer Mode,然后依次选择 Settings、Connectors、Add MCP server,粘贴相同的 URL 并完成 OAuth 提示。Cursor:使用本 README 顶部的一键徽章;也可以将 {"mcpServers":{"stayingapi":{"url":"https://mcp.stayingapi.com/mcp"}}} 添加到 ~/.cursor/mcp.json,供所有项目使用,或添加到 .cursor/mcp.json,仅供单个项目使用。其他 MCP 客户端也可以使用——将相同的 URL 添加为 Streamable HTTP 服务即可;支持 Dynamic Client Registration 的客户端会自动协商 OAuth,无需其他配置。无论哪种方式,设置都不到一分钟,因为该服务由托管:无需安装、管理运行时,也无需持续更新软件包。各客户端的完整说明见 快速安装;其中只列出了经过官方文档验证的配置,因为错误的配置块会浪费唯一一次安装机会。
费用是多少?
注册即可获得 300 个免费额度,无需绑定银行卡;在 REST API 中,stay_test_ 沙盒密钥会永久免费返回确定性测试数据,因此你可以在不花费任何费用的情况下构建并测试完整集成。之后采用按额度计费,当前的单次调用费用和套餐价格见定价页面——本 README 刻意不列出付费金额,以免这里的信息过时。无论套餐如何,以下三项始终免费:失败、结果为空和被拦截的调用(creditsCharged 为 0)、get_job 轮询,以及所有 REST 沙盒调用。MCP 和 REST 共用同一余额,因此添加 MCP 服务不会产生第二笔账单。验证账户邮箱后即可使用实时额度;验证前也能完整使用沙盒。
StayingAPI 是否隶属于 Airbnb、Booking.com、Vrbo 或 Google Hotels?
不隶属于。StayingAPI 是一项独立服务。**StayingAPI 与 Airbnb、Booking.com、Vrbo 或 Google Hotels 均无关联,也未获得其认可或赞助。这些名称是各自所有者的商标,在此仅用于说明 StayingAPI 的 API 和 MCP 服务可以查询的数据来源。**我们不是任何预订平台的合作伙伴、转售商或授权集成方,也未与其中任何平台签订协议,且这些平台均未认可、审查或批准本项目。本 README、platforms[] 枚举和工具参数中出现的平台名称,纯粹是用于说明特定调用针对哪个数据来源的描述性标签,就像价格比较工具会列出其查询的商店名称一样。StayingAPI 不会预订、取消或修改预订:全部七个工具都严格为只读工具,并标注为 readOnlyHint: true,完全没有写入工具。如果你需要实际预订住宿,请使用每处房源随附的规范 url,直接在相应平台上预订。
获取密钥——300 个免费额度,无需银行卡 · MCP 文档 · 定价 · 状态
根据 MIT 许可证发布。StayingAPI 是一项独立服务,与任何预订平台均无关联,也未获得其认可。平台名称是各自所有者的商标。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。