Airbnb Search & Listings - MCP Bundle (MCPB)

一个全面的 MCP Bundle，用于搜索 Airbnb 房源，配有高级筛选功能，并可获取详细的房源信息。它作为 Model Context Protocol (MCP) 服务器构建，并以 MCP Bundle (MCPB) 格式打包，便于安装，同时可与兼容的 AI 应用程序配合使用。

🚀 不想自己运行本地服务器？试试 openbnb.ai

👉 openbnb.ai 是一个托管的 MCP 服务器，解决同一个问题——搜索 Airbnb 房源——而且无需任何本地设置。

如果你不想亲自安装和运行此服务器，openbnb.ai 是一个独立的、完全托管的替代方案，你可以直接从 MCP 客户端连接使用。它比这个开源服务器提供的功能更丰富：

• ✅ 零配置 — 不需要 Node.js，不需要 npx，没有配置文件，也不用管理更新

• ✅ 高级筛选 — 比这里提供的基础工具具备更丰富的搜索控制

• ✅ MCP UI — 提供用于浏览结果的交互式 UI 组件，而不只是纯文本

• ✅ 托管与维护 — 为维护

前往 openbnb.ai 查看设置说明，以及你的 MCP 客户端的连接方式。

如果你选择自行托管这个开源服务器，请继续阅读。

功能特性

🔍 高级搜索功能

• 基于位置的搜索，支持城市、州和地区

• 国际位置支持，通过客户端地理编码实现，因此非美国查询（例如 “Paris, France”、“Copenhagen, Denmark”）也会返回正确的城市结果

• Google Maps Place ID 集成，用于精准定位

• 按房源类型筛选，支持整套房源、独立房间、合住房间或酒店房间

• 日期筛选，支持入住和退房日期

• 住客配置，包括成人、儿童、婴儿和宠物

• 价格范围筛选，支持最低和最高价格限制

• 分页支持，用于浏览大量分页结果

🏠 详细的房源信息

• 全面的房源详情，包括设施、政策与亮点

• 位置信息，包括坐标和街区详情

• 房屋守则与政策，帮助你做出明智的预订决策

• 房源描述和关键功能预览

• 直接链接到 Airbnb 房源，方便进行预订

🛡️ 安全性与合规性

• Robots.txt 合规，并支持可配置的覆盖选项，用于测试

• 请求超时管理，防止请求挂起

• 增强的错误处理，日志详尽

• 了解速率限制，并合理地使用 API

• 通过 MCPB 用户设置进行安全配置

安装

在 Claude Desktop 中

本扩展以 MCP Bundle (.mcpb) 文件形式打包。安装方法：

1. 从最新发布版本下载 .mcpb 文件

2. 打开该文件——Claude Desktop 会显示安装对话框

3. 按需配置扩展设置

如需忽略 robots.txt，打开 Claude Desktop 设置，找到该扩展并启用 **Ignore robots.txt 忽略开关，即可。

在 Cursor 等工具中

开始之前，请确保你的桌面已安装 Node.js，以便 npx 正常工作。

1. 前往：Cursor Settings > Tools & Integrations > New MCP Server

2. 在 mcp.json 中添加以下选项之一：

   {
     "mcpServers": {
       "airbnb": {
         "command": "npx",
         "args": [
           "-y",
           "@openbnb/mcp-server-airbnb"
         ]
       }
     }
   }

   如需对所有请求忽略 robots.txt，请使用带 --ignore-robots-txt 参数的版本：

   {
     "mcpServers": {
       "airbnb": {
         "command": "npx",
         "args": [
           "-y",
           "@openbnb/mcp-server-airbnb",
           "--ignore-robots-txt"
         ]
       }
     }
   }

3. 重启。

配置

该扩展提供以下用户可配置的选项：

Ignore robots.txt

• 类型：布尔值（复选框）

• 默认值：false

• 说明：请求 Airbnb 时绕过 robots.txt 限制

• 建议：除非是测试所需，否则请保持禁用

禁用第三方地理编码

• 类型：布尔值（复选框）

• 环境变量：DISABLE_GEOCODING

• 默认值：false

• 说明：跳过 Photon/Nominatim 地理编码步骤，让 Airbnb 自行解析位置字符串。启用该开关会恢复 PR 之前的行为——每次搜索只与 airbnb.com 通信，不产生任何第三方调用。

• 建议：除非你确实需要完全避免第三方出站流量，否则请保持禁用。启用后，非美国地区的搜索结果可能不正确。参见外部服务。

工具

airbnb_search

利用全面的筛选选项（扩展选项）搜索 Airbnb 房源。

参数：

• location（必填）：要搜索的位置（例如 “San Francisco, CA”）。当未提供 placeId 时，服务器会通过 Photon/Nominatim 在客户端对该字符串进行地理编码——参见外部服务。

• placeId（可选）：Google 地图地点 ID。它会覆盖 location，并完全跳过客户端地理编码（无第三方调用）。

• checkin（可选）：入住日期，YYYY-MM-DD 格式

• checkout（可选）：退房日期，YYYY-MM-DD 格式

• adults（可选）：成人数（默认：1）

• children（可选）：儿童数（默认：0）

• infants（可选）：婴儿数（默认：0）

• pets（可选）：宠物数量（默认：0）

• minPrice（可选）：每人每晚最低

• maxPrice（可选）：每人每晚最高

• cursor（可选）：用于浏览结果的分页游标

• propertyType（可选）：将 entire_home、private_room、shared_room 或 hotel_room 按属性类型进行筛选

• ignoreRobotsText（可选）：对本次请求覆盖 robots.txt

返回结果：

• 包含房源详情、价格和直接链接的搜索结果

• 用于继续浏览更多结果的分页信息

• 供参考的搜索 URL

airbnb_listing_details

获取特定 Airbnb 房源的详细信息。

参数：

• id（必填）：Airbnb 房源 ID

• checkin（可选）：入住日期，YYYY-MM-DD 格式

• checkout（可选）：退房日期，YYYY-MM-DD 格式

• adults（可选）：成人数量（默认：1）

• children（可选）：儿童数量（默认：0）

• infants（可选）：婴儿数量（默认：0）

• pets（可选）：宠物数量（默认：0）

• ignoreRobotsText（可选）：对本次请求覆盖 robots.txt

返回结果：

• 详细的房源信息，包括：

  • 坐标和位置

  • 设施与设备，以 seeAllAmenitiesGroups 形式返回——这是一个以设施类别为键的对象，因此可以直接访问某个类别。Airbnb 以划掉（不可用）显示的设施，会被归到其自身的 "Not included" 类别下：

    {
      "seeAllAmenitiesGroups": {
        "Bathroom": "Hair dryer",
        "Heating and cooling": "AC - split type ductless system, Heating",
        "Not included": "Dryer, Hot water"
      }
    }

  • 房屋守则与政策

  • 房源亮点与描述

  • 房源直链

Technical Details 技术细节

架构

• 运行时：Node.js 18+

• 协议：基于 stdio 传输的 Model Context Protocol (MCP)

• 格式：MCP Bundle (MCPB) v0.3

• 依赖：极少的第三方依赖，以保证安全性和可靠性

外部服务

除了 airbnb.com 外，服务器还会向两个第三方服务发起地理编码请求，将位置查询转换为准确的地图边界框。这可以绕过 Airbnb 自己的服务端地理编码服务，后者会对许多非美国查询产生错误结果（例如 “Paris, France” 会落到 Vendée；“Copenhagen, Denmark” 会落到 Wisconsin（威斯康星州））。

每次搜索只会将该位置字符串随请求发送到地理编码服务——不会发送其他请求字段、不涉及 IP 地理定位，也不包含跟踪标识。当然，位置字符串就是用户输入的同一个字符串。

**选择无视（退出机制）：**跳过地理编码器有两种方式：

• 单次请求：传入显式的 placeId。当提供 placeId 时，服务器会直接使用 Airbnb 自己的地点查询，不产生任何第三方调用。

• 全局全局：设置环境变量 DISABLE_GEOCODING=true。服务器将完全跳过 Photon/Nominatim，并把原始 location 字符串传给 Airbnb。这会恢复出现 PR 之前每个搜索的行为，并保证零第三方出站流量——代价是，对 Airbnb 自带地理编码器无法扩展处理的非美国位置，搜索结果不再可靠。默认为 false。

如果一个地理编码服务不可达或返回无结果，服务器会回退到直接向 Airbnb 发送位置字符串的方式，与之前的做法一致。因此这类服务中断时，最坏的情况是让它恢复到以前的（不太精确的）结果，而不会导致搜索整体失败。

错误处理

• 完整的时间戳日志

• 当 Airbnb 页面结构变化时优雅降级

• 网络请求超时保护

• 提供详细的错误消息，便于排查

安全措施

• 默认遵守 robots.txt

• 请求超时限制

• 输入验证与清洗

• 安全的环境变量处理

• 不存储敏感数据

性能

• 使用 Cheerio 高效解析 HTML

• 正确的位置进行请求缓存

• 内存占用低

• 启动和响应快速，响应时间短

兼容性

• 平台：macOS、Windows、Linux

• Node.js：18.0.0 或更高

• Claude Desktop：0.10.0 或更高版本

• 其他 MCP 客户端：兼容任何支持 MCP 的应用程序

开发

从源码构建

# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes during development
npm run watch

测试

# Build, then run both suites
npm test

npm test 通过 stdio 驱动已构建的服务器，并真实调用工具：

• test-extension.js — MCP 握手、工具列表、搜索、房源详情，以及地理编码路径模式（Photon、Nominatim 回退）

• test-amenities.js — 对多个线上房源进行设施提取，检查 Airbnb 中划掉线/排除的设施是否从未出现在房源提供的设施中

两者都会通过网络访问 airbnb.com 和地理编码服务，因此它们需要网络连接，并可能因 Airbnb 更改页面结构而失败——这正是测试的意义所在，但也意味着它们并不适合作为无人值守的 CI 门禁。

服务器也可以直接运行：

# Run with robots.txt compliance (default)
node dist/index.js

# Run with robots.txt ignored (for testing)
node dist/index.js --ignore-robots-txt

法律与道德规范

• 尊重 Airbnb 的服务条款：本扩展用于合法的研究和预订帮助

• 遵守 robots.txt：扩展默认遵守 robots.txt

• 速率限制：注意请求频率，避免对 Airbnb 服务器造成过大的压力

• 数据使用：仅出于合法目的提取公开信息

支持

• 问题反馈：在 GitHub Issues 上提交 Bug 报告和功能需求

• 文档：更多文档可在仓库中查看

• 社区：参与关于 MCP 和 MCPB 开发的讨论

License 许可证

MIT 许可证 - 详见 LICENSE 文件。

Contributing 贡献指南

欢迎贡献！请阅读贡献指南，并为任何改进提交拉取请求。

注意：本扩展与 Airbnb, Inc. 没有关联。它是一个独立工具，旨在帮助用户搜索和分析公开可用的 Airbnb 房源。