Labsco
chia-health logo

Nomad Stays

from chia-health

The world's platform for finding and booking digital nomad friend accommodation

🔥🔥✓ VerifiedFreeQuick setup
#email#automation#calendar#database#git#maps

🏡 Nomad Stays MCP Server

Find the perfect remote work accommodation worldwide

API Version 0.5.0 | 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. This API supports both the Model Context Protocol (MCP) for AI assistants and standard REST endpoints for direct integration.

🔌 API Endpoints

Browse available REST endpoints

🤖 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

🔌 REST API Endpoints

GET /health

Health check endpoint to verify the server is running.

Response

{ "status": "healthy", "timestamp": "2025-01-15T10:30:00Z" }

GET /api/stays

Retrieve a list of stays with optional filtering.

Query Parameters

countrycode (string) Optional

ISO 3166-1 alpha-2 country code (e.g., PT, ES, TH, MX, CO)

limit (integer) Optional

Maximum number of results to return (default: 10, max: 100)

Example Request

GET https://mcp.nomadstays.com/api/stays?countrycode=PT&limit=5

Example Response

{ "stays": [ { "id": "stay_001", "name": "Lisbon Co-living Hub", "description": "Modern co-living space in the heart of Lisbon", "country": "Portugal", "countryCode": "PT", "city": "Lisbon", "pricePerMonth": 850, "currency": "EUR", "amenities": ["high_speed_wifi", "dedicated_desk", "kitchen", "coworking_space"], "coordinates": { "latitude": 38.7223, "longitude": -9.1393 }, "images": ["[https://example.com/image1.jpg"](https://example.com/image1.jpg%22%5C)], "bookingUrl": "https://www.nomadstays.com/stays/001" } ], "count": 1, "filters": { "countryCode": "PT", "limit": 5 } }

GET /api/stays/{id}

Retrieve detailed information about a specific stay.

Path Parameters

id (string) Required

Unique identifier for the stay

GET https://mcp.nomadstays.com/api/stays/stay_001

{ "id": "stay_001", "name": "Lisbon Co-living Hub", "description": "Modern co-living space in the heart of Lisbon with fast WiFi...", "longDescription": "Full detailed description with multiple paragraphs...", "country": "Portugal", "countryCode": "PT", "city": "Lisbon", "neighborhood": "Príncipe Real", "pricePerMonth": 850, "currency": "EUR", "amenities": ["high_speed_wifi", "dedicated_desk", "kitchen", "coworking_space"], "wifiSpeed": 200, "coordinates": { "latitude": 38.7223, "longitude": -9.1393 }, "images": ["https://example.com/image1.jpg", "[https://example.com/image2.jpg"](https://example.com/image2.jpg%22%5C)], "bookingUrl": "https://www.nomadstays.com/stays/001", "reviews": { "average": 4.5, "count": 42 } }

🤖 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

Connect this server to Claude in just 2 steps:

Step 1: Open your Claude configuration file:

  • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add this configuration:

{ "mcpServers": { "nomadstays": { "command": "npx", "args": [ "mcp-remote", "https://mcp.nomadstays.com/mcp", "--transport", "http-first" ] } } }

After adding, restart Claude. You can then ask: "Find me remote work stays in Portugal"

For Claude.ai Web Users

  • Go to Settings → Features → Model Context Protocol

  • Click "Add Server"

  • Enter server URL: https://mcp.nomadstays.com/mcp

  • Save and 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" } } }

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

📊 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 connection

  • dedicated_desk - Dedicated workspace

  • kitchen - Full kitchen access

  • coworking_space - On-site coworking space

  • gym - Fitness facilities

  • pool - Swimming pool

  • parking - Parking available

  • pet_friendly - Pets allowed

🆘 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 searchHelpCenter to find articles by keyword or question.

  • Use getHelpCenterArticle to fetch a specific article by its ID.

  • Use listHelpCenterCategories to 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 /mcp preferred)

  • Implement the get_allocation tool — takes property_id, start_date, end_date

  • Return a ranges array with only reduced-allocation date periods

  • Secure with a Bearer token — NomadStays sends Authorization: Bearer <key> on every request

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= 

# 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, see the SUPPLIER_SPEC.md on GitHub or contact [email protected] 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.5.0 | Made for digital nomads and remote workers 🌎