Airbnb Search & Listings - MCP Bundle (MCPB)

Airbnb 숙소 검색을 위한 종합적인 MCP Bundle입니다. 고급 필터링 기능과 상세한 숙소 정보 조회를 지원합니다. 호환되는 AI 애플리케이션에서 쉽게 설치하고 사용할 수 있도록 MCP Bundle(MCPB) 형식으로 패키징된 Model Context Protocol(MCP) 서버입니다.

🚀 로컬 서버를 실행하고 싶지 않으신가요? openbnb.ai를 사용해 보세요

👉 openbnb.ai는 로컬 설정 없이 Airbnb 숙소 검색이라는 동일한 문제를 해결하는 호스팅 MCP 서버입니다.

이 서버를 직접 설치하고 실행하는 번거로움을 피하고 싶다면, **openbnb.ai**는 MCP 클라이언트에서 직접 연결할 수 있는 별도의 완전 호스팅 대안입니다. 이 오픈소스 서버가 제공하는 기능을 뛰어넘습니다:

• ✅ 제로 설정 — Node도, npx도, 설정 파일도, 관리할 업데이트도 필요 없습니다.

• ✅ 고급 필터 — 여기 제공되는 기본 도구보다 더 풍부한 검색 제어 기능

• ✅ MCP UI — 단순 텍스트가 아니라 결과를 탐색할 수 있는 대화형 UI 구성 요소

• ✅ 관리 및 유지보수 — 계속 실행되도록 관리해 드립니다.

설치 방법과 MCP 클라이언트 연결 정보는 **openbnb.ai**에서 확인하세요.

오픈소스 서버를 직접 호스팅하고 싶다면 계속 읽어보세요.

기능

🔍 고급 검색 기능

• 위치 기반 검색 — 도시, 주, 지역 지원

• 국제 위치 지원 — 클라이언트 측 지오코딩을 통해 비미국 쿼리(예: "Paris, France", "Copenhagen, Denmark")도 올바른 도시의 결과를 반환

• Google Maps Place ID 통합으로 정확한 위치 타게팅

• 숙소 유형 필터링 — 전체 숙소, 개인실, 공용실, 호텔 객실 지원

• 날짜 필터링 — 체크인, 체크아웃 날짜 지원

• 게스트 설정 — 성인, 어린이, 유아, 반려동물 포함

• 가격 범위 필터링 — 최소/최대 가격 제한 지원

• 페이지네이션 지원 — 많은 결과를 탐색할 때 사용

🏠 상세 숙소 정보

• 종합적인 숙소 정보 — 편의시설, 정책, 하이라이트 포함

• 위치 정보 — 좌표 및 이웃 지역 상세 정보 포함

• 하우스 규칙 및 정책 — 정보에 기반한 예약 결정을 위해

• 숙소 설명 및 주요 특징

• Airbnb 숙소로 연결되는 직접 링크 — 편리한 예약을 위해

🛡️ 보안 및 규정 준수

• robots.txt 준수 — 테스트용으로 재정의 가능한 설정 제공

• 요청 시간 초과 관리 — 요청 멈춤 방지

• 향상된 오류 처리 — 상세 로깅 포함

• 요청률 제한 인식 — Airbnb 서버에 부담을 주지 않는 API 사용

• 안전한 구성 — MCPB 사용자 설정을 통해

설치

Claude Desktop 사용 시

이 확장 프로그램은 MCP Bundle(.mcpb) 파일로 패키징되어 있습니다. 설치 방법:

1. 최신 릴리스에서 .mcpb 파일을 다운로드합니다.

2. 파일을 엽니다 — Claude Desktop에 설치 대화상자가 표시됩니다.

3. 필요에 따라 확장 프로그램 설정을 구성합니다.

robots.txt를 무시하고 싶다면, Claude Desktop 설정을 열고 확장 프로그램으로 이동한 후 Ignore robots.txt 토글을 활성화하세요.

Cursor 등에서 사용

시작하기 전에 npx가 작동하도록 Node.js가 데스크톱에 설치되어 있는지 확인하세요.

1. Cursor 설정 > 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. 다시 시작합니다.

구성

이 확장 프로그램은 다음과 같은 사용자 구성 옵션을 제공합니다:

Ignoring robots.txt 무시

• 유형: Boolean(체크박스)

• 기본값: false

• 설명: Airbnb에 요청을 보낼 때 robots.txt 제한을 우회합니다.

• 권장사항: 테스트 목적이 아니라면 비활성 상태로 유지하세요.

제3자 지오코딩 비활성화

• 유형: Boolean(체크박스)

• 환경 변수: DISABLE_GEOCODING

• 기본값: false

• 설명: Photon/Nominatim 지오코딩 단계를 건너뛰고 Airbnb가 위치 문자열을 자체적으로 해석하도록 합니다. 이 옵션을 활성화하면 PR 이전의 동작으로 복원됩니다 — 모든 검색은 airbnb.com에만 요청되며 제3자 호출이 없습니다.

• 권장사항: 제3자 외부 트래픽을 완전히 차단해야 하는 특별한 상황이 아니라면 비활성 상태로 유지하세요. 활성화하면 미국 이외 지역 검색 결과가 부정확해질 수 있습니다. 외부 서비스 참조.

도구

airbnb_search

Airbnb 숙소를 포괄적인 필터링 옵션과 함께 검색합니다.

매개변수:

• location (필수): 검색할 위치(예: "San Francisco, CA"). placeId 없이 제공하면 서버는 이 문자열을 Photon/Nominatim을 통해 클라이언트 측에서 지오코딩합니다 — 외부 서비스 참조.

• placeId (선택): Google Maps Place ID. location를 대체하며 클라이언트 측 지오코딩을 완전히 건너뜁니다(제3자 호출 없음).

• checkin (선택): YYYY-MM-DD 형식의 체크인 날짜

• checkout (선택): YYYY-MM-DD 형식의 체크아웃 날짜

• adults (선택): 성인 수(기본값: 1)

• children (선택): 어린이 수(기본값: 0)

• infants (선택): 유아 수(기본값: 0)

• pets (선택): 반려동물 수(기본값: 0)

• minPrice (선택): 1박당 최저 가격

• maxPrice (선택): 1박당 최대 가격

• cursor (선택): 결과 탐색을 위한 페이지네이션 커서

• propertyType (선택): 숙소 유형 필터 — entire_home, private_room, shared_room 또는 hotel_room

• ignoreRobotsText (선택): 이 요청에 대해 robots.txt 재정의

반환값:

• 숙소 정보, 가격, 직접 링크가 포함된 검색 결과

• 추가 결과 탐색을 위한 페이지네이션 정보

• 참조용 검색 URL

airbnb_listing_details

특정 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+

• 프로토콜: 표준입출력(stdin/정전력/流出) 기반의 Model Context Protocol(MCP)

• 형식: MCP Bundle(MCPB) v0.3

• 의존성: 보안과 안정적 운영을 위해 외부의존 + 사용.

"의존성": 보안과 안정성을 위한 최소한의 외부 의존성.

외부 서비스

airbnb.com 외에도 서버는 검색 정확도를 위해 두 개의 제3서비스에 지오코딩 요청을 보냅니다. 이는 정확한 위치를 나타내는 경계 상자를 구하는 방법입니다. 이는 많은 비미국 쿼리(예: "Paris, France"가 프랑스의 Vendée로, "Copenhagen, Denmark"가 미국 위스콘신으로 처리하는) 잘못 인식하는 Airbnb 자체 서버 측 지오코더를 우회합니다.

각 검색은 요청의 location 문자열만 지오코더에 전달합니다 — 그 외 필드나 IP 위치 추적, 인식기 등은 전송되지 않습니다. 위치 문자열은 사용자가 입력한 그대로의 문자열입니다.

지오코더 건너뛰기: 간단한 두 가지 방법이 있습니다:

• 요청별: 명시적인 placeId를 설정합니다. placeId가 있으면 서버가 Airbnb의 직접 장소 조회를 사용하며 제3자 호출이 없습니다.

• 전역 설정: DISABLED_GEOCODING=true를 환경 변수로 설정합니다. 서버는 Photon/Nominatim을 완전히 건너뛰고 원래 위지 문자열을 Airbnb에 그대로 보냅니다. 이렇게 하면 모든 검색이 PR 이전의 동작으로 돌아가고 제삼자 발신 트래픽이 없음을 보장합니다. 대신 Airbnb 자체 지오코더가 잘못 처리하지 않는 비미국 지역 검색 결과를 올바르게 반환하려는 경우 부정확한 결과가 발생할 수 있습니다. 기본값은 true는 아닌 false입니다.

지오코더에 도달할 수 없거나 결과를 얻지 못하면, 이전과 동일하게 위치 문자열을 Airbnb에 직접 보내는 방식으로 전환합니다. 따라서 중단 시의 최악의 경우는 검색 자체가 실패하는 것이 아니라 국제 검색기를 이전(오류가 있는) 동작으로 낮추는 것뿐입니다.

오류 처리

• 타임스탬프를 포함한 종합적인 오류 로깅

• Airbnb 페이지 구조가 변경된 경우에도 발생 가능한 완화(우아한 생성)

• 네트워크 요청에 대한 시간 초과(timeout) 방어

• 문제 해결을 위한 상세한 오류 메시지

보안 대책

• 기본 robots.txt 구문을 준수함

• 요청에 대한 timeout 제한

• 입력 값 검증 및 무해화(sanitize)

• 안전한 환경 변수 처리

• 민감한 데이터를 저장하지 않음

성능

• 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 핸드 셰이크, 도구 목록, 검색, listing 상세 조회, 지오코딩 경로(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

개발

소스에서 빌드

# 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를 이용하세요.

• 문서: 저장소에 추가 문서가 있습니다.

• 커뮤니티: MCP 및 MCPB 개발에 관한 논의에 참여하세요.

License

MIT License — 자세한 내용은 LICENSE 파일을 참조하십시오.

기여

이 문서에 대한 기여도 환영합니다. 버그, 기능 요청, 기여 사항은 GitHub Issues를 통해 남겨주세요.

기여는 환영합니다! 기여 가이드라인을 읽고 개선 사항이 있으면 pull request를 제출해 주세요.

참고: 이 확장 프로그램은 Airbnb, Inc.와 제휴 관계가 아닙니다. 이 도구는 사용자가 공개적으로 제공되는 Airbnb 숙소 목록을 검색하고 분석할 수 있도록 설계된 독립 도구입니다.