mcpField
H
Hotel & Vacation Rental MCP - live prices & reviews across Booking, Airbnb, Vrbo & Google Hotels

Hotel & Vacation Rental MCP - live prices & reviews across Booking, Airbnb, Vrbo & Google Hotels

远程服务
stayingapi.com地图与出行03 天前更新

关于 Hotel & Vacation Rental MCP - live prices & reviews across Booking, Airbnb, Vrbo & Google Hotels

StayingAPI 的 Hotel & Vacation Rental MCP 服务可跨 Booking.com、Airbnb、Vrbo 和 Google Hotels 搜索住宿、可订情况、价格及评价。七个只读工具以统一格式返回数据,并支持跨平台比价。

主要功能

  1. 01跨四个平台搜索住宿
  2. 02逐日检查可订情况
  3. 03跨平台比较价格
  4. 04获取房源详情和评价
  5. 05统一住宿数据格式

适用场景

  1. 01按地点和日期查找住宿
  2. 02比较同一房源在各网站的价格
  3. 03检查每日可订情况和最少入住晚数
  4. 04汇总住宿评价

MCP 相关

通过托管的 Streamable HTTP MCP 服务提供七个只读工具。客户端通过 OAuth 2.1 验证身份;工具支持搜索、检查可订情况、比价、获取评价和轮询任务。

配置

远程服务无需本地安装。选择你使用的客户端,复制配置或使用一键安装。

服务地址https://mcp.stayingapi.com/mcp
一键复制安装命令
Claude CodeTerminal
Cursor.cursor/mcp.json
VS Code.vscode/mcp.json
Claude Desktopclaude_desktop_config.json
Windsurf~/.codeium/windsurf/mcp_config.json

命令在终端中运行;JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。

工具

详细介绍

StayingAPI

酒店与度假租赁 MCP——提供 Booking.com、Airbnb、Vrbo 和 Google Hotels 上的实时价格、房态与评价

只需向 AI 提问,即可搜索住宿、比较 Booking.com、Airbnb、Vrbo 和 Google Hotels 上的价格,并获取评价。一个托管式 MCP,注册即享 300 点免费额度,无需银行卡。
七个只读工具——搜索、房态、房源详情、价格、跨 OTA 价格比较、评价和任务轮询——适用于 Claude、ChatGPT、Cursor、Claude Code 及任何 MCP 客户端。

在 Cursor 中安装 300 点免费额度,无需银行卡

网站 文档 OpenAPI MIT 许可证 Glama 质量评分

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

快速安装

要求:

  • 一个 StayingAPI 账户(注册——可获 300 个免费额度,无需银行卡)
  • 一个支持 OAuth 2.1 的 MCP 客户端(Claude、ChatGPT、Cursor 和大多数其他客户端)。MCP 服务仅通过 OAuth 为你登录;API 密钥(stay_live_... / stay_test_...)用于 REST API

建议:添加规则,让 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 中安装
  1. 启用开发者模式:设置 → 应用和连接器 → 高级设置。
  2. 前往设置 → 连接器 → 添加 MCP 服务(在连接器面板中创建)。
  3. 粘贴服务 URL:
https://mcp.stayingapi.com/mcp
  1. 根据提示完成 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

按地点、日期、入住人数和筛选条件搜索多个平台上的房源,并合并到同一套架构中。这是覆盖面最广的端点,也是「一套架构,适用于所有平台」的最佳示例。

参数类型必填说明
locationstring是地点名称(Split, HR)或 lat,lng
checkIn / checkOutdate否YYYY-MM-DD;必须同时提供;日期不能在过去
adults / children / childAges[] / roomsinteger否childAges[] 的长度必须等于 children
propertyType[]enum[]否hotel | apartment | house | villa | cottage | other
amenities[]enum[]否标准化设施分类体系
minBedrooms / priceMin / priceMax / minGuestRatingnumber否在标准化后应用筛选条件
platforms[]enum[]否airbnb | booking | vrbo | google;决定扇出范围
limit / cursor / sort / currencymixed否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

查询某个平台上一个已知房源(或一批房源)在指定日期范围内逐日的可订情况。每一天都会报告是否可订、最少入住晚数要求,以及是否允许入住、退房和预订。

参数类型必填说明
platformenum是单个平台;不支持扇出
listingId / listingIds[] / urlstring三选一房源 ID、多个房源 ID,或完整的房源 URL
startDate / endDatedate是日期不能在过去;时间范围最长为 365 天
onlyAvailableboolean否如果为 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 服务的形式提供。

MCPREST 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 开放资源集: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 是一项独立服务,与任何预订平台均无关联,也未获得其认可。平台名称是各自所有者的商标。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。