Airbnb MCP Server

Instructions

Implementation Reference

• index.ts:174-333 (handler)

  The handler function that implements the core logic of the airbnb_search tool: constructs Airbnb search URL from parameters, checks robots.txt compliance, fetches and scrapes the HTML using cheerio to extract search results including listings with URLs, prices, ratings, etc., and returns structured JSON.

  async function handleAirbnbSearch(params: any) {
    const {
      location,
      placeId,
      checkin,
      checkout,
      adults = 1,
      children = 0,
      infants = 0,
      pets = 0,
      minPrice,
      maxPrice,
      cursor,
      ignoreRobotsText = false,
    } = params;
  
    // Build search URL
    const searchUrl = new URL(`${BASE_URL}/s/${encodeURIComponent(location)}/homes`);
    
    // Add placeId
    if (placeId) searchUrl.searchParams.append("place_id", placeId);
    
    // Add query parameters
    if (checkin) searchUrl.searchParams.append("checkin", checkin);
    if (checkout) searchUrl.searchParams.append("checkout", checkout);
    
    // Add guests
    const adults_int = parseInt(adults.toString());
    const children_int = parseInt(children.toString());
    const infants_int = parseInt(infants.toString());
    const pets_int = parseInt(pets.toString());
    
    const totalGuests = adults_int + children_int;
    if (totalGuests > 0) {
      searchUrl.searchParams.append("adults", adults_int.toString());
      searchUrl.searchParams.append("children", children_int.toString());
      searchUrl.searchParams.append("infants", infants_int.toString());
      searchUrl.searchParams.append("pets", pets_int.toString());
    }
    
    // Add price range
    if (minPrice) searchUrl.searchParams.append("price_min", minPrice.toString());
    if (maxPrice) searchUrl.searchParams.append("price_max", maxPrice.toString());
    
    // Add room type
    // if (roomType) {
    //   const roomTypeParam = roomType.toLowerCase().replace(/\s+/g, '_');
    //   searchUrl.searchParams.append("room_types[]", roomTypeParam);
    // }
  
    // Add cursor for pagination
    if (cursor) {
      searchUrl.searchParams.append("cursor", cursor);
    }
  
    // Check if path is allowed by robots.txt
    const path = searchUrl.pathname + searchUrl.search;
    if (!ignoreRobotsText && !isPathAllowed(path)) {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            error: robotsErrorMessage,
            url: searchUrl.toString()
          }, null, 2)
        }],
        isError: true
      };
    }
  
    const allowSearchResultSchema: Record<string, any> = {
      listing : {
        id: true,
        name: true,
        title: true,
        coordinate: true,
        structuredContent: {
          mapCategoryInfo: {
            body: true
          },
          mapSecondaryLine: {
            body: true
          },
          primaryLine: {
            body: true
          },
          secondaryLine: {
            body: true
          },
        }
      },
      avgRatingA11yLabel: true,
      listingParamOverrides: true,
      structuredDisplayPrice: {
        primaryLine: {
          accessibilityLabel: true,
        },
        secondaryLine: {
          accessibilityLabel: true,
        },
        explanationData: {
          title: true,
          priceDetails: {
            items: {
              description: true,
              priceString: true
            }
          }
        }
      },
      // contextualPictures: {
      //   picture: true
      // }
    };
  
    try {
      const response = await fetchWithUserAgent(searchUrl.toString());
      const html = await response.text();
      const $ = cheerio.load(html);
      
      let staysSearchResults = {};
      
      try {
        const scriptElement = $("#data-deferred-state-0").first();
        const clientData = JSON.parse($(scriptElement).text()).niobeMinimalClientData[0][1];
        const results = clientData.data.presentation.staysSearch.results;
        cleanObject(results);
        staysSearchResults = {
          searchResults: results.searchResults
            .map((result: any) => flattenArraysInObject(pickBySchema(result, allowSearchResultSchema)))
            .map((result: any) => { return {url: `${BASE_URL}/rooms/${result.listing.id}`, ...result }}),
          paginationInfo: results.paginationInfo
        }
      } catch (e) {
          console.error(e);
      }
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            searchUrl: searchUrl.toString(),
            ...staysSearchResults
          }, null, 2)
        }],
        isError: false
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            error: error instanceof Error ? error.message : String(error),
            searchUrl: searchUrl.toString()
          }, null, 2)
        }],
        isError: true
      };
    }
  }

• index.ts:18-75 (schema)

  The Tool object definition for airbnb_search, including name, description, and detailed inputSchema for validation of parameters like location, dates, guests, prices, etc.

  const AIRBNB_SEARCH_TOOL: Tool = {
    name: "airbnb_search",
    description: "Search for Airbnb listings with various filters and pagination. Provide direct links to the user",
    inputSchema: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "Location to search for (city, state, etc.)"
        },
        placeId: {
          type: "string",
          description: "Google Maps Place ID (overrides the location parameter)"
        },
        checkin: {
          type: "string",
          description: "Check-in date (YYYY-MM-DD)"
        },
        checkout: {
          type: "string",
          description: "Check-out date (YYYY-MM-DD)"
        },
        adults: {
          type: "number",
          description: "Number of adults"
        },
        children: {
          type: "number",
          description: "Number of children"
        },
        infants: {
          type: "number",
          description: "Number of infants"
        },
        pets: {
          type: "number",
          description: "Number of pets"
        },
        minPrice: {
          type: "number",
          description: "Minimum price for the stay"
        },
        maxPrice: {
          type: "number",
          description: "Maximum price for the stay"
        },
        cursor: {
          type: "string",
          description: "Base64-encoded string used for Pagination"
        },
        ignoreRobotsText: {
          type: "boolean",
          description: "Ignore robots.txt rules for this request"
        }
      },
      required: ["location"]
    }
  };

• index.ts:120-123 (registration)

  Registration of the airbnb_search tool in the AIRBNB_TOOLS array, which is used to list available tools via ListToolsRequestHandler.

  const AIRBNB_TOOLS = [
    AIRBNB_SEARCH_TOOL,
    AIRBNB_LISTING_DETAILS_TOOL,
  ] as const;

• index.ts:488-490 (registration)

  Server request handler for listing tools, which returns the AIRBNB_TOOLS array including airbnb_search.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: AIRBNB_TOOLS,
  }));

• index.ts:499-502 (registration)

  Dispatch/registration in the CallToolRequestSchema handler: switch case that routes 'airbnb_search' calls to the handleAirbnbSearch function.

  switch (request.params.name) {
    case "airbnb_search": {
      return await handleAirbnbSearch(request.params.arguments);
    }