You can use this read-only MCP server to find CuddlyNest hotel destinations and pull detailed public hotel listing information with live room prices and availability.
cuddlynest_search — resolve a city/area string to matching CuddlyNest destination candidates (name, city/state/country, coordinates, property count), with optional stay dates/guest/currency parameters echoed for later use.
cuddlynest_listing_details — given a hotel URL or numeric product_id, return static listing data (name, description, address, coordinates, star rating, amenities, images) plus live room options for the requested dates.
Retrieve room-level pricing details: unit price, currency, remaining rooms, guest capacity, price breakdown, room filters, and cancellation policy type/text.
Get reliable cheapest-room price via rooms.fromPrice, plus partner names supplying the offers (e.g. dida travels, hxpro, ratehawk).
Control stay parameters (check-in/check-out, adults, children/child ages, infants, number of rooms) and currency for price lookups.
Optionally bypass robots.txt for listing-page fetches and set a custom browser timeout via environment variable.
No booking or payment functionality — it is read-only by design.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CuddlyNest Search & Listings MCP Server Search for hotels in Barcelona and show prices for 2 adults this weekend"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for searching CuddlyNest hotels and retrieving listing details, including room options, prices, availability and cancellation policies.
Read-only by design: search and listing details only. No booking, no payment.
This server reads that data the same way a visitor does: it opens the real, public listing page in a headless browser (Playwright/Chromium), lets the page's own JavaScript load the rooms, waits for them to render, and reads the result out of the DOM.
Data | Source |
Name, description, address, coordinates, star rating, amenities, images | Listing page |
Room title, partner, | Rendered listing page DOM, via a React-fiber walk ( |
Destination → place candidates + top hotels |
|
Destination → broader city hotel list (~60–250) |
|
|
|
|
|
extractRoomsFromDom() walks every price-shaped text node (COL$742,637), then
walks up its React fiber tree to the nearest ancestor component whose props
carry both unit_price and roomGroups. Those props are the room offer the
page already rendered.
This is coupled to CuddlyNest's current frontend internals (a React prop shape,
not a stable contract). If they ship a frontend change it can start returning
zero rooms even though the public page still shows prices. The single place to
update is the detector condition 'unit_price' in p && 'roomGroups' in p in
scrape-listing.ts. npm run e2e:sansiraka is meant to
catch that early (non-zero exit, not a silent empty result).
The fromPriceText ("From COL$…") field uses a looser heuristic and can come
back null even on a healthy scrape; rooms.fromPrice (cheapest extracted
unit) is the reliable figure.
Related MCP server: Amadeus Hotel API MCP Server
Node.js 18+
A Chromium build for Playwright. npm install runs playwright install chromium automatically (postinstall); if that is blocked in your
environment, run npx playwright install chromium once by hand.
Published as cuddlynest-mcp on
npm and listed in the official MCP registry
as io.github.mafedelahoz/cuddlynest-mcp.
{
"mcpServers": {
"cuddlynest": {
"command": "npx",
"args": ["-y", "cuddlynest-mcp"]
}
}
}Add "--ignore-robots-txt" to args to bypass robots.txt for the
listing-page fetches. CUDDLYNEST_SCRAPE_TIMEOUT_MS (default 35000) caps how
long the browser waits for prices to render.
An MCPB bundle (.mcpb) for Claude Desktop is attached to each
GitHub release — note it
does not bundle Chromium, so run npx playwright install chromium once after
installing it that way.
Default transport is stdio. For a hosted deployment, run it over Streamable HTTP:
node dist/index.js --http 8080 # or: MCP_TRANSPORT=http PORT=8080 node dist/index.js
# POST http://<host>:8080/mcp — JSON-RPC (stateless, no sessions)
# GET http://<host>:8080/health — livenessBoth tools are annotated readOnlyHint: true — they never write, book, or pay.
cuddlynest_searchSearch a destination and the top hotels there, from public CuddlyNest APIs
(autosuggestion-2-0 for the fuzzy match, discovery-pages geo pages for the
broader city list). Prices are not here — pass a hotel's productId to
cuddlynest_listing_details.
Parameter | Required | Description |
| yes | City / area string, e.g. |
| no | Omit the |
| no | Also pull the geo-page city list (~60–250 hotels) when it can be resolved and verified against the destination — a few extra requests (default |
| no | echoed back for downstream use |
Returns: { query, guests, places[], city, hotelSource, hotelCount, hotels[], note }.
Each hotels[] entry: productId, name, url, slug, propertyType,
starRating, guestRating (/10) + guestRatingText, reviewCount, and — from
the geo page — images[], distanceFromCenterKm, featuredAmenities[].
hotelSource is "autosuggest" or "autosuggest+geopage". The list is
top-matches scale, not full inventory — CuddlyNest's real results page
(/sr/…) is bot-blocked and Disallowed in robots.txt.
cuddlynest_listing_detailsStatic basics and rooms/pricing for one hotel.
Parameter | Required | Description |
| yes | Listing URL or numeric |
| for pricing |
|
| no | defaults 2 / 0 / – / 0 / 1 |
| no | ISO 4217, default |
| no | ignore robots.txt for the static fetch |
Returns: { productId, hotelUrl, guests, staticListing, staticError, rooms, roomsError, notes }.
rooms.units[] is the extracted room offers, each with title, partnerName,
unitPrice, currency, remainingRooms, guests, cancellationPolicyType,
cancellationPolicyText, priceBreakdown, roomFilters. rooms also carries
fromPrice, partnersSeen, listingUrl, scrapedAt.
npm install # installs deps + Chromium (postinstall)
npm run build # sync-version + tsc -> dist/
npm run typecheck
npm test # offline: smoke test (stdio) + scraper tests
npm run e2e:sansiraka # ONLINE: real scrape of cuddlynest.com, structural asserts
npm run watchindex.ts — MCP server, tool schemas, stdio and Streamable HTTP transports,
robots.txt handling
cuddlynest.ts — hotel-URL parsing, static-listing ld+json parse,
destination autosuggestion, result shaping
scrape-listing.ts — resolveListingPath, buildListingUrl, scrapeListing
(headless browser), extractRoomsFromDom (React-fiber walk)
util.ts — generic object/JSON helpers
MIT — see LICENSE.
Get details for a specific CuddlyNest hotel: static basics (name, location, description, amenities, images) from the listing page, plus room options, prices, availability and cancellation policies read from the public listing page rendered in a headless browser.
| Name | Required | Description | Default |
|---|---|---|---|
| hotel | Yes | CuddlyNest hotel URL or numeric product_id. The product_id is the trailing number in a listing URL, e.g. https://www.cuddlynest.com/hotel/us/le-meridien-boston-cambridge-4264955 -> 4264955. | |
| rooms | No | Number of rooms (default: 1) | |
| adults | No | Number of adults (default: 2) | |
| checkin | No | Check-in date (YYYY-MM-DD) | |
| infants | No | Number of infants (default: 0) | |
| checkout | No | Check-out date (YYYY-MM-DD) | |
| children | No | Number of children (default: 0, or derived from childAges) | |
| currency | No | ISO 4217 currency code for prices (default: USD), e.g. USD, EUR, COP | |
| childAges | No | Age of each child at check-in, e.g. [2, 7]. Sets `children` when given. | |
| ignoreRobotsText | No | Ignore robots.txt for the listing-page fetch on this request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint annotation by explaining that data is 'read from the public listing page rendered in a headless browser.' This usefully discloses the data source and the browser-rendering approach. It does not mention failure modes or latency, but it adds meaningful behavioral context on top of the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence with no filler. It front-loads the core purpose and packs the key output categories into a well-organized list, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does a good job listing the main return categories: static basics, room options, prices, availability, and cancellation policies. Combined with the fully documented input schema and readOnly/openWorld annotations, it is sufficient for an agent to select and invoke the tool correctly. Minor gaps such as exact response structure or error behavior are not critical here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters clearly. The description adds high-level output context but no additional parameter-level semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Get details for a specific CuddlyNest hotel' and enumerates what is included (static basics, room options, prices, availability, cancellation policies). This makes it easy to distinguish from the sibling cuddlynest_search, which is about searching/discovering hotels rather than retrieving a specific listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a specific CuddlyNest hotel' clearly indicates this tool is for when the agent already has a hotel URL or product_id. It does not explicitly name cuddlynest_search as the alternative or state exclusions, but the contrast with the sibling tool is apparent and the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search CuddlyNest for a destination and the top hotels there. Returns place candidates (city/region + coordinates + total property count) and a list of hotels — name, listing URL, star + guest rating, and (when available) images, distance from the centre and key amenities. Pass a hotel's product_id from the results to cuddlynest_listing_details for live rooms and prices. The hotel list is top-matches scale (~10-60), not the full inventory.
| Name | Required | Description | Default |
|---|---|---|---|
| rooms | No | Number of rooms (default: 1) | |
| adults | No | Number of adults (default: 2) | |
| checkin | No | Check-in date (YYYY-MM-DD) | |
| infants | No | Number of infants (default: 0) | |
| checkout | No | Check-out date (YYYY-MM-DD) | |
| children | No | Number of children (default: 0, or derived from childAges) | |
| currency | No | ISO 4217 currency code for prices (default: USD), e.g. USD, EUR, COP | |
| childAges | No | Age of each child at check-in, e.g. [2, 7]. Sets `children` when given. | |
| hotelsOnly | No | Return only the hotel list, skipping place candidates (default false). | |
| destination | Yes | Destination to search (city / area), e.g. 'Santa Marta, Colombia'. | |
| fullCityList | No | Also pull the broader city hotel list (~60) from the geo-page API when it can be resolved — a couple of extra requests. Default true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and open-world, and the description adds useful behavioral context: it returns a limited top-matches list rather than the full inventory, includes fields only 'when available', and can return place candidates. This goes beyond what annotations declare without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, each adding distinct value: purpose, return payload, next-step routing, and scale caveat. There is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 11 parameters and no output schema, the description gives enough on selection and invocation: what the search returns, the shape of hotel entries, the limited scale, and how to proceed to listing details. The parameter details are handled by the fully covered schema, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 11 parameters. The description adds no new parameter-level meaning; it only explains the overall result shape. This matches the baseline for well-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names the action and resource ('Search CuddlyNest for a destination and the top hotels there') and the return types are specified (place candidates, hotel list). It also names the sibling tool in the handoff ('Pass a hotel's product_id ... to cuddlynest_listing_details'), so an agent can distinguish search from details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this tool is the entry-point search and that live rooms/prices are obtained via cuddlynest_listing_details, which is an explicit alternative routing. It also sets expectations that the list is top-matches (~10-60) and not full inventory, but it doesn't state explicit 'do not use when...' conditions beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1cuddlynest_listing_details1 field changedInput schema / properties / destinationSlugRemoved value: -{
- "description": "CuddlyNest internal destination slug for the hotel's city (e.g. 'SantaMartaMagdalenaColombia'). Optional — derived from the listing page's city/state/country when omitted.",
- "type": "string"
-}cuddlynest_search2 fields changedInput schema / properties / fullCityListAdded value: +{
+ "description": "Also pull the broader city hotel list (~60) from the geo-page API when it can be resolved — a couple of extra requests. Default true.",
+ "type": "boolean"
+}Input schema / properties / hotelsOnlyAdded value: +{
+ "description": "Return only the hotel list, skipping place candidates (default false).",
+ "type": "boolean"
+}v0.1.0cuddlynest_listing_detailscuddlynest_searchScored across 2 tools
The two tools occupy completely separated stages of the workflow: search discovers destinations and top hotels, while listing_details drills into one hotel using a product_id. There is no overlap in purpose or output.
Both names share a cuddlynest_ prefix, making the server's brand clear, but one uses an imperative verb (search) while the other is a noun phrase (listing_details). This minor inconsistency prevents a perfect score.
Two tools is borderline for a typical MCP server, though the count fits the narrow search-and-details purpose. It feels slightly thin because there is no tool for direct lookups or other listing workflows.
The described lifecycle is complete: cuddlynest_search produces both destination candidates and hotels with product IDs, and cuddlynest_listing_details consumes those IDs to return live rooms, prices, and policy details. No obvious dead end exists in the intended flow.
Booking.com stays by destination and dates, and full property details, as structured JSON.
Manage hotels via the apaleo PMS API: reservations, folios, invoices, rates and availability.
Book real hotel and resort stays from any AI agent: all-in pricing, hosted Stripe checkout, no key.
Hotel booking MCP server. Search, book, and manage reservations across 250K+ properties worldwide.
