Skip to main content
Glama
Sign In

Airbnb MCP

by ai.wondel
OverviewDiscussionsAdmin

Search Airbnb stays

airbnb_search

Search places to stay on Airbnb — apartments, houses, rooms, cabins, villas and hotels — in any city, region or country, for given dates and guests: price for the stay, rating and review count, Guest favourite / Superhost badges, beds and baths, coordinates, photos and a link that opens the same stay. Filter by room type, minimum bedrooms and total price. One page is up to 18 stays; page 2–15 for more (Airbnb caps a search at 270). Pass a listing's id to airbnb_listing for amenities, house rules and the host. Scraped live from airbnb.pl (typically ~1 s via direct fetch; ~10 s when it falls back to an unblocker). WITH checkin + checkout, price is the TOTAL for the whole stay for the given guests, all fees and taxes included (Airbnb's EU total-price display), in currency; price_per_night = price ÷ nights; price_before_discount is the struck-through total when discounted; price_breakdown lists Airbnb's own lines (e.g. '2 noce x 245,00 zł' → 490, 'Podatki' → 8). Stays of 28+ nights are quoted per month: price null, price_per_month set. WITHOUT dates, Airbnb prices each listing for its own suggested stay (its stay, usually ~5 nights soon), so prices are not comparable and not a quote — a note says so; pass dates to quote a trip. Only stays bookable for the given dates are listed. Result shape: { source, fetchedAt, query, search_url, place: { query, place_id, resolved, city, region, country }, stay: { checkin, checkout, nights } | null, guests: { adults, children, infants, pets }, currency, total_count, page, total_pages, count, listings: [...], note? } — the list key is listings; total_count is Airbnb's count of matches (more than it lets you page through). Each listing: { id, url, name, kind, city, details, bedrooms, beds, baths, host_type, rating, review_count, is_new, guest_favorite, superhost, badges, free_cancellation, stay, price_basis, price, price_per_night, price_per_month, price_before_discount, nights, currency, price_text, price_breakdown, lat, lng, photos }. rating is 0–5; kind/city/details/price_text are Airbnb's Polish wording (e.g. kind 'Mieszkanie' = apartment, 'Pokój' = room, 'Dom' = house); host_type is business | private; coordinates are approximate (Airbnb blurs them). An empty match answers count: 0 with a note saying why and what to change — that is a successful result, not an error.

Input Schema

NameRequiredDescriptionDefault
pageNoResults page, 1-based (18 stays per page, at most 15 pages). Default 1.
petsNoPets (limits results to pet-friendly stays). Default 0.
placeYesWhere to stay — a city, region, area or country, as you would type it into Airbnb: 'Zakopane', 'Kraków', 'Mazury', 'Lisbon, Portugal', 'Tuscany'. Add the country to disambiguate. Latin script (diacritics are fine).
adultsNoAdults (13+). Default 2.
checkinNoArrival date, YYYY-MM-DD (from today to about two years ahead). Pass together with checkout; omit both for Airbnb's own suggested dates.
infantsNoInfants under 2 (not counted as guests). Default 0.
checkoutNoDeparture date, YYYY-MM-DD, after checkin (at most 365 nights; 28+ nights are quoted per month).
childrenNoChildren aged 2–12. adults + children ≤ 16. Default 0.
currencyNo3-letter ISO currency for prices, e.g. 'PLN' (default), 'EUR', 'USD', 'GBP'.
no_cacheNoForce a fresh fetch and bypass this server's result cache (5 min). Default false.
price_maxNoMaximum total price for the whole stay incl. fees, whole units of `currency` (needs dates).
price_minNoMinimum total price for the whole stay incl. fees, whole units of `currency` (needs dates).
room_typeNoOnly 'entire_home' (the whole place to yourself) or only 'private_room'. Default: any.
min_bedroomsNoAt least this many bedrooms.

Output Schema

NameRequiredDescriptionDefault
noteNo
pageYes
stayNo
countYes
placeYes
queryYes
guestsNo
sourceYes
currencyNo
listingsYes
fetchedAtYes
search_urlYes
total_countNo
total_pagesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: discloses the data source (scraped live from airbnb.pl), latency profile (~1 s direct fetch, ~10 s via unblocker fallback), the 270-result / 15-page cap, the 5-minute cache implied by no_cache, currency/price-basis semantics, 28+ night monthly quoting, approximate blurred coordinates, and Polish-language field values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and key caveats, and most sentences earn their place, but the long enumeration of the full result object and per-listing field list is largely redundant given an output schema exists. It is dense and information-rich but would benefit from trimming the return-shape prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter scraping tool with no annotations, it covers pricing basis, pagination limits, caching, latency, language quirks, failure semantics and sibling handoff. Nothing an agent needs to call it correctly or interpret results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: `price` is the all-in total for the stay for the given guests, `price_per_night` = price ÷ nights, `price_before_discount` is the struck-through total, `page` caps at 270 results across 15 pages. It doesn't restate per-parameter constraints (guests caps, date formats) that the schema already covers, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (search places to stay on Airbnb) plus property types and geographic scope, and explicitly separates itself from airbnb_listing ('Pass a listing's `id` to airbnb_listing for amenities, house rules and the host'). An agent can route between the two siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-tos and when-nots: pass checkin+checkout to get a comparable quoted total, omit both to get Airbnb's suggested-stay prices which are 'not comparable and not a quote'; use `page` 2–15 for more results; use airbnb_listing for amenities. It even explains that an empty match is a successful result with guidance, not an error.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Airbnb MCP toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources