Airbnb MCP Server

Airbnb 搜索与房源 - MCP Bundle（MCPB）

一款功能全面的 MCP Bundle，可搜索 Airbnb 房源，支持高级筛选，并可获取详细的房源信息。它是一个 Model Context Protocol（MCP）服务，以 MCP Bundle（MCPB）格式打包，可轻松安装并与兼容的 AI 应用搭配使用。

---

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

👉 openbnb.ai 是一款托管式 MCP 服务，可解决同样的问题——搜索 Airbnb 房源——而无需进行任何本地设置。

如果你不想自己安装并运行此服务，openbnb.ai 是一个独立的全托管替代方案，可直接从你的 MCP 客户端连接。它提供了超越此开源服务的功能：

• ✅ 零配置 — 无需 Node、无需 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 设置，找到该扩展，并启用 忽略 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. 重启。

配置

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

忽略 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 Maps 地点 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"
      }
    }
    

  • 房屋规则和政策

  • 房源亮点和描述

  • 房源的直接链接

技术详情

架构

• 运行时：Node.js 18+
• 协议：通过 stdio 传输的 Model Context Protocol (MCP)
• 格式：MCP Bundle (MCPB) v0.3
• 依赖项：尽量减少外部依赖，以确保安全性和可靠性

外部服务

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

服务	端点	用途	说明
Photon	photon.komoot.io	主要地理编码器；每次不带 placeId 的搜索都会调用	由 Komoot 托管的免费 OSM 服务。每次搜索发送一个请求。
Nominatim	nominatim.openstreetmap.org	后备地理编码器；仅当 Photon 未返回边界框时调用	受 OSMF 使用政策约束（最多约 1 req/sec）。

每次搜索只会向地理编码器发送请求中的 location 字符串，不会发送其他请求字段、IP 地理位置或跟踪标识符。当然，location 字符串就是用户输入的相同字符串。

**选择退出：**有两种方式可以跳过地理编码器：

• **针对单个请求：**提供明确的 placeId。如果存在 placeId，服务会直接使用 Airbnb 自己的地点查询功能，不会发起任何第三方调用。
• **全局：**将环境变量 DISABLE_GEOCODING=true。服务会完全跳过 Photon/Nominatim，并将原始位置字符串传给 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.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 上报告错误和功能请求
• 文档：仓库中提供了其他文档
• 社区：加入关于 MCP 和 MCPB 开发的讨论

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

参与贡献

欢迎贡献！请阅读贡献指南，并提交拉取请求以改进项目。

---

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