digital nomad stays logo brand Nomad Stays Homepage

🏡 Nomad Stays MCP Server

Find the perfect remote work accommodation worldwide

API Version 0.1.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

📊 Data Model

Understand the stay object structure

🔌 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"], "bookingUrl": "https://www.nomadstays.com/stays/001" } ], "count": 1, "filters": { "countryCode": "PT", "limit": 5 } }
GET /api/stays/continent/{continent}

Retrieve stays by continent name.

Path Parameters

continent (string) Required

Continent name (e.g., Europe, Asia, Africa, North America, South America, Oceania)

Query Parameters

limit (integer) Optional

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

Example Request

GET https://mcp.nomadstays.com/api/stays/continent/Europe?limit=10
GET /api/stays/location/{location}

Flexible location search across city, state, location name, country, and description fields.

Path Parameters

location (string) Required

Search term (e.g., Paris, Beach, California, Mountain)

Query Parameters

limit (integer) Optional

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

Example Request

GET https://mcp.nomadstays.com/api/stays/location/Paris?limit=10
GET /api/stays/lifestyle/{lifestyle}

Filter stays by lifestyle/genre category.

Path Parameters

lifestyle (string) Required

Lifestyle category (e.g., Digital Nomad, Beach Life, City Living, Mountain Retreat)

Query Parameters

limit (integer) Optional

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

Example Request

GET https://mcp.nomadstays.com/api/stays/lifestyle/Digital%20Nomad?limit=10
GET /api/lifestyles

Returns all active lifestyle/genre categories available.

Example Request

GET https://mcp.nomadstays.com/api/lifestyles

Example Response

{ "lifestyles": [ "Digital Nomad", "Beach Life", "City Living", "Mountain Retreat", "Rural Escape" ], "count": 5 }
GET /api/stays/{id}

Retrieve detailed information about a specific stay.

Path Parameters

id (string) Required

Unique identifier for the stay

Example Request

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

Example Response

{ "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"], "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.

🚀 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": { "url": "https://mcp.nomadstays.com" } } }

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

For Claude.ai Web Users

  1. Go to Settings → Features → Model Context Protocol
  2. Click "Add Server"
  3. Enter server URL: https://mcp.nomadstays.com
  4. 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" } } }

Available Tools

Tool Name Description Parameters
🔍 Search & Filter
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)
getStayByID Retrieve detailed information about a specific stay id (string)
📅 Availability & Booking
checkStayAvailability Check availability for a stay between specific dates stayId (string), checkIn (string), checkOut (string), roomType (string, optional)
findNearestAvailability Find the nearest available dates around a preferred check-in stayId (string), preferredCheckIn (string), minLengthOfStay (number), maxLengthOfStay (number, optional), searchWindowDays (number, optional)
getAvailabilityByMonth Get an availability calendar for a specific month stayId (string), year (number), month (number), minLengthOfStay (number)
getRoomAvailability Check availability for a specific room roomId (string), checkIn (string), checkOut (string)
📚 Reference & Metadata
getAllLifestyles Retrieve all lifestyle/genre categories available None
getAllAmenities Retrieve all available amenities in the system None
getRoomAmenities Get amenities for a specific room roomId (string)

📊 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

💡 Usage Examples

Find stays in Portugal

curl "https://mcp.nomadstays.com/api/stays?countrycode=PT&limit=10"

Find stays in Europe

# REST API - Example with European countries: curl "https://mcp.nomadstays.com/api/stays?countrycode=PT&limit=10" curl "https://mcp.nomadstays.com/api/stays?countrycode=ES&limit=10" curl "https://mcp.nomadstays.com/api/stays?countrycode=GR&limit=10" # Or using MCP tool: getStaysByContinent # Searches by continent name (Europe, Asia, Africa, etc.)

Find stays in Paris or near beaches

# REST API - General search (returns all stays, filter results): curl "https://mcp.nomadstays.com/api/stays?countrycode=FR&limit=20" # Or using MCP tool: getStaysByLocation # Flexible search across city, state, location name, country, and descriptions # Examples: 'Paris', 'Beach', 'California', 'Mountain'

Budget-friendly stay search (MCP)

{ "tool": "getStaysByBudget", "arguments": { "durationDays": 28, "maxPrice": 1500, "currency": "USD", "countryCode": "ES", "checkInDate": "2026-02-01", "limit": 5 } }

Find nearest available dates (MCP)

{ "tool": "findNearestAvailability", "arguments": { "stayId": "stay_001", "preferredCheckIn": "2026-03-10", "minLengthOfStay": 7, "maxLengthOfStay": 14, "searchWindowDays": 30 } }

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"

🌍 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.

⚡ 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:

Nomad Stays MCP Server v0.1.0 | Made for digital nomads and remote workers 🌎

Sign up and start saving today

Become a Member

Want to become a Stay Partner?

How We Work