Nomad Stays
디지털 노마드 친화적인 숙소를 찾고 예약하는 글로벌 플랫폼입니다.
문서
🏡 Nomad Stays MCP Server
Find the perfect remote work accommodation worldwide
API Version 0.6.2 | Base URL:https://mcp.nomadstays.com
📖 Overview
The Nomad Stays MCP Server provides access to a curated database of remote-work-friendly accommodations around the world via the Model Context Protocol (MCP), for use with AI assistants like Claude and ChatGPT.
New: Trusted Stay Partners can now connect their own AI assistant (see Setting Up Your AI Assistant as a Trusted Stay Partner below) so it can look up and update their Stay listings, rooms, pricing packages, organisational data, business profile, and photos on their behalf. See the🔐 Owner-Scoped Lookup Tools and ✏️ Owner-Scoped Write Tools sections below.
🤖 MCP Protocol
Use with AI assistants like Claude
💡 Examples
See sample requests and responses
🆘 Help Center
Access help articles and support via MCP tools
📊 Data Model
Understand the stay object structure
🏨 Supplier Integration
Push your availability to NomadStays in real time
🤖 Model Context Protocol (MCP)
This server implements the MCP specification, allowing AI assistants to discover and use stays data naturally in conversation. Now includes Help Center tools for searching and retrieving support articles directly via MCP.
🚀 Quick Setup for Claude Desktop
Connect this server to Claude Desktop in a couple of clicks — no config file editing needed:
Step 1: In Claude Desktop, go to Settings → Connectors and click Add custom connector.
Step 2: Enter the server URL:
https://mcp.nomadstays.com/mcp
Claude Desktop will open a sign-in prompt — log in with your NomadStays account and click Allow. You can then ask:"Find me remote work stays in Portugal"
For Claude.ai and ChatGPT Web Users
- Go to Settings → Connectors (Claude.ai) or the equivalent connector/MCP settings in ChatGPT
- Click "Add custom connector" / "Add Server"
- Enter server URL:
https://mcp.nomadstays.com/mcp - Complete the NomadStays sign-in prompt and click Allow, then start using it in conversations!
POST / MCP Protocol
MCP protocol endpoint for AI assistant integration.
Integration
To use this server with Claude or other MCP-compatible assistants, configure your MCP client with:
{ "mcpServers": { "nomadstays": { "url": "https://mcp.nomadstays.com/mcp" } } }
🔑 Setting Up Your AI Assistant as a Trusted Stay Partner (Step-by-Step)
If you manage a Stay on NomadStays, you can let your own AI assistant read and update your listing, rooms, prices, and photos for you. You don't need to know how to code — it's a self-service connection using your NomadStays login, no waiting on the NomadStays team. This works with ChatGPT, Claude.ai, and Claude Desktop's Connectors.
Step 1 — Turn on two-factor authentication
Before you can connect an agent, your NomadStays account needs two-factor authentication (2FA) turned on. This protects your listing in case access is ever lost or shared. Go to Enable two-factor authentication and follow the on-screen instructions if you haven't already.
Step 2 — Add the connector in your AI assistant
In ChatGPT or Claude.ai, add a new connector/MCP server pointing at https://mcp.nomadstays.com/mcp. In Claude Desktop, add it under Settings → Connectors instead. Your assistant will open a NomadStays sign-in and authorization prompt — log in and click Allow. Access is granted immediately, and you can review or revoke connected agents any time from your Stay profile page.
Step 3 — Try it out
Start a new conversation and ask something like: "List my Stays" or "Show me the current price packages on my Stay." If your assistant responds with your real listing data, it's working.
Questions? Contact tech@nomadstays.com.
Available Tools
| Tool Name | Description | Parameters |
|---|---|---|
| 🆘 Help Center Tools | ||
| searchHelpCenter | Search help articles by keyword or question | query (string), category (optional string), limit (optional number) |
| getHelpCenterArticle | Retrieve a specific help article by ID | id (string) |
| listHelpCenterCategories | List all available help center categories | None |
| 🔍 Search & Filter Tools | ||
| getStaysByCountry | Search stays by 2-letter country code or partial country name | countrycode (string), limit (number) |
| getStaysByContinent | Filter stays by continent (Europe, Asia, Africa, etc.) | continent (string), limit (number) |
| getStaysByLocation | Search across City, State, location name, country, and description | location (string), limit (number) |
| getStaysByLifestyle | Find stays by lifestyle category | lifestyle (string), limit (number) |
| getStaysByBudget | Search stays within budget and duration with FX conversion | durationDays, maxPrice, currency, countryCode (optional), checkInDate (optional), limit (optional) |
| getStaysByAmenities | Search stays by amenities with fuzzy matching | amenities (array), matchType (optional), minWifiSpeed (optional), limit (optional) |
| getStaysByWiFiSpeed | Find all stays with WiFi download speed greater than 10Mbps. | minWiFiDownloadSpeed (number), limit (number) |
| getStayByID | Get detailed information about a specific stay | id (number) |
| 📅 Availability & Booking Tools | ||
| checkStayAvailability | Check room availability for specific dates | stayId, checkIn, checkOut, roomType (optional) |
| findNearestAvailability | Find nearest available dates near preferred check-in | stayId, preferredCheckIn, minLengthOfStay, maxLengthOfStay (optional), searchWindowDays (optional) |
| getAvailabilityByMonth | Get availability calendar for a specific month | stayId, year, month, minLengthOfStay |
| getRoomAvailability | Check availability for a specific room | roomId, checkIn, checkOut |
| 📚 Reference & Metadata Tools | ||
| getAllLifestyles | Retrieve all available lifestyle categories | None |
| getAllAmenities | Retrieve all available amenities in the system | None |
| getRoomAmenities | Get amenities for a specific room | roomId |
| 🔐 Owner-Scoped Lookup Tools (require an MCP agent token) | ||
| getMyStays | List all Stays owned by the account bound to the MCP agent token | None |
| getMyStayDetail | Get a Stay's current title, description, and listed status | stayId |
| getMyStayRooms | List all rooms configured on a Stay | stayId |
| getMyStayPackages | List all pricing packages and price tiers on a Stay | stayId |
| getMyStayOrganisationalData | Get a Stay's address, check-in/out policy, and cancellation policy | stayId |
| getMyStayContacts | Get a Stay's public-facing contact details | stayId |
| getMyStayFacilities | Get a Stay's facility checkboxes for a given facility group | stayId, group |
| getMyStayPhotos | List a Stay's photos by area (listing, main, workspace, host) | stayId |
| getMyBusinessProfile | Get the Trusted Stay Partner account's business profile (legal name, VAT/registration numbers) | None |
| getRoomTypeOptions | List valid room types for a Stay — boutique Stays get Boutique1–Boutique6 only, standard Stays get ordinary room types | stayId |
| getRoomFacilityOptions | List all room-level facility options | None |
| getCurrencyOptions | List valid currencies for package pricing | None |
| getBusinessModelOptions | List valid values for a Stay's business model — read-only (not editable via MCP or the host UI itself), but the value it holds determines the sellPrice formula and whether advertisingEndpoint applies to packages | None |
| getFacilityGroups | List all facility groups a Stay's facilities are organised into | None |
| getStayTypeOptions | List valid values for a Stay's main accommodation type | None |
| getCountryOptions | List valid countries, with names and 2-letter codes | None |
| getCancellationPolicyOptions | List valid cancellation policy values | None |
| getAdditionalInformationOptions | List valid values for a picklist field (e.g. Pets Allowed, Children Allowed, Parking) used in organisational data | filterName |
| ✏️ Owner-Scoped Write Tools (require an MCP agent token) | ||
| updateStayDetail | Update a Stay's title and/or description | stayId, title (optional), description (optional) |
| createStayRoom | Create a new room on a Stay | stayId, roomTitle, roomDescription (optional), beds (optional), maxPerson (optional), and more |
| updateStayRoom | Update an existing room on a Stay | stayId, roomId, plus any room fields to change |
| deleteStayRoom | Soft-delete a room from a Stay | stayId, roomId |
| createStayPackage | Create a new pricing package on a Stay, optionally with initial price tiers | stayId, packageName, prices (optional array), and more |
| updateStayPackage | Update a pricing package. Supplying prices replaces ALL price rows for that package | stayId, packageId, plus any package/price fields to change |
| deleteStayPackage | Permanently delete a pricing package and all its price tiers (hard delete, unlike rooms) | stayId, packageId |
| updateStayOrganisationalData | Update a Stay's address, check-in/out policy, pets/children/parking, cancellation policy | stayId, plus any organisational fields to change |
| updateStayContacts | Update a Stay's public-facing contact details | stayId, plus any contact fields to change |
| updateStayFacilities | Set the full list of selected facility checkboxes for one facility group on a Stay. Anything not included is unchecked | stayId, group, facilityDetailIds (full replacement list) |
| updateHostBusinessProfile | Update the Trusted Stay Partner account's business profile. Never touches bank or tax-ID details | businessName, vatNumber, businessNumber, entityAccount — all optional |
| uploadStayPhoto | Upload a photo to a Stay's listing, main, workspace, host, or room photo area. Supply a public https:// URL or base64-encoded bytes. Every photo is validated for JPEG format, size, minimum resolution (1920×1080 landscape, or 1080×1920 portrait for the "host" area) and is re-encoded server-side before storage | stayId, area, url or base64, roomId (required when area is "room") |
| deleteStayPhoto | Delete a Stay-level photo by area and filename | stayId, area, fileName |
| reorderStayPhotos | Reorder a Stay's photos within a given area | stayId, area, fileNames (full ordered list) |
| deleteRoomPhoto | Delete a room-level photo by area and filename | stayId, roomId, roomArea, fileName |
| reorderRoomPhotos | Reorder a room's photos within a given area | stayId, roomId, roomArea, fileNames (full ordered list) |
📊 Data Model
Stay Object
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier for the stay |
| name | string | Name of the accommodation |
| description | string | Short description of the stay |
| country | string | Full country name |
| countryCode | string | ISO 3166-1 alpha-2 country code |
| city | string | City name |
| priceRange | string | Weekly price range (e.g., "From EUR 250 per week") |
| priceCurrency | string | Currency code (e.g., EUR, USD) |
| amenities | array | List of available amenities |
| WiFiDownloadSpeed | number | WiFi download speed in Mbps (optional) |
| WiFiUploadSpeed | number | WiFi upload speed in Mbps (optional) |
| location_name | string | Location name from Location table |
| location_country | string | Location country from Location table |
| PetsAllowed | boolean | Whether pets are allowed |
| coordinates | object | GeoLat and GeoLng coordinates |
| bookingUrl | string | URL to book the stay |
Common Amenities
Standard amenity identifiers used in the API:
high_speed_wifi- High-speed internet connectiondedicated_desk- Dedicated workspacekitchen- Full kitchen accesscoworking_space- On-site coworking spacegym- Fitness facilitiespool- Swimming poolparking- Parking availablepet_friendly- Pets allowed
💡 Usage Examples
Find stays in Portugal
curl "https://mcp.nomadstays.com/api/stays?countrycode=PT&limit=10"
Search the Help Center for WiFi questions
# Using MCP tool: searchHelpCenter # Example: Find help articles about WiFi { "tool": "searchHelpCenter", "parameters": { "query": "WiFi" } }
Find stays in Europe
# Using MCP tool: getStaysByContinent # Searches by continent name
Find stays in Paris or near beaches
# Using MCP tool: getStaysByLocation # Searches across city, state, location name, and descriptions
Get all stays (no filter)
curl "https://mcp.nomadstays.com/api/stays?limit=50"
Get specific stay details
curl "https://mcp.nomadstays.com/api/stays/stay\_001"
Using with Claude (MCP)
Once configured, simply ask Claude naturally:
"Can you help me find remote work accommodations in Thailand?"
"Show me stays in Paris with good WiFi"
"I want to stay near a beach in Europe"
🆘 Help Center Integration
The MCP server now provides direct access to the Nomad Stays Help Center. You can search for help articles, retrieve specific articles by ID, and list available categories using the new MCP tools. This enables AI assistants and users to get support and answers to common questions programmatically.
- Use
searchHelpCenterto find articles by keyword or question. - Use
getHelpCenterArticleto fetch a specific article by its ID. - Use
listHelpCenterCategoriesto browse available help topics.
For manual browsing, visit the Nomad Stays Help Center.
🌍 Supported Countries
Currently available country codes (examples):
PT - Portugal
ES - Spain
TH - Thailand
MX - Mexico
CO - Colombia
ID - Indonesia
GR - Greece
IT - Italy
Note: Use the API to discover the complete list of available countries.
🏨 Supplier / PMS Integration
If you operate a property management system (PMS) or channel manager, you can sync your availability calendar directly with NomadStays. Two integration modes are available:
Option 1 — MCP Server (Pull)
Run your own MCP server that exposes a get_allocation tool. NomadStays polls it hourly and writes the returned availability into our booking system automatically.
- Expose your server over HTTPS (Streamable HTTP
POST /mcppreferred) - Implement the
get_allocationtool — takesproperty_id,start_date,end_date - Return a
rangesarray with only reduced-allocation date periods - Secure with a Bearer token — NomadStays sends
Authorization: Bearer <key>on every request
Option 2 — Webhook Push Recommended
Push availability changes to NomadStays the moment they occur — no waiting for the next poll cycle. When webhook push is enabled, NomadStays reduces polling to a once-daily safety check.
POST /api/mcp/availability-push/{stayId} Base: https://www.nomadstays.com
Authentication
Sign every request with HMAC-SHA256 using the shared secret NomadStays provisions during onboarding:
X-NomadStays-Signature: sha256=<lowercase-hex>
# Python example
import hmac, hashlib
sig = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
Payload
{
"room_id": "your-room-identifier",
"ranges": [
{ "start_date": "2026-07-10", "end_date": "2026-07-15", "allocation": 0 },
{ "start_date": "2026-08-01", "end_date": "2026-08-05", "allocation": 1 }
]
}
Only include date ranges where availability is reduced from normal. Send "ranges": [] to clear all blocks.
Response Codes
| Status | Meaning |
|---|---|
| 200 OK | Accepted — {"received": true, "reductions": N} |
| 401 | Missing or incorrect signature |
| 404 | Stay or room not found |
For the full integration specification including code examples in Python and Node.js, contact tech@nomadstays.com to begin onboarding.
⚡ Rate Limits & Best Practices
- Rate limit: 100 requests per minute per IP
- Use appropriate limit parameters to avoid over-fetching
- Cache responses when possible to reduce API calls
- Always check the health endpoint before making bulk requests
🆘 Support
For questions, issues, or feature requests:
- Contact: Contact Page
Nomad Stays MCP Server v0.6.2 | Made for digital nomads and remote workers 🌎