🏡 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.
🔌 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
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
/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
/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
/api/lifestyles
Returns all active lifestyle/genre categories available.
Example Request
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
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
- Go to Settings → Features → Model Context Protocol
- Click "Add Server"
- Enter server URL:
https://mcp.nomadstays.com - 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 |
|---|---|---|
getStaysByCountry |
Search stays by 2-letter country code (e.g., 'MA', 'US') or partial country name (e.g., 'Antigua') | countrycode (string), limit (number) |
getStaysByContinent |
Filter stays by continent (e.g., 'Europe', 'Asia', 'Africa', 'North America', 'South America', 'Oceania') | continent (string), limit (number) |
getStaysByLocation |
Flexible location search across City, State, location name, country, and description fields (e.g., 'Paris', 'Beach', 'California') | location (string), limit (number) |
getStaysByLifestyle |
Filter stays by lifestyle/genre category (e.g., 'Digital Nomad', 'Beach Life', 'City Living', 'Mountain Retreat'). Each stay can belong to multiple lifestyle categories. | lifestyle (string), limit (number) |
getLifestyles |
Returns all active lifestyle/genre categories available. Use this to discover what lifestyle categories exist before searching with getStaysByLifestyle. | None |
📊 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
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'
Get specific stay details
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
Nomad Stays MCP Server v0.1.0 | Made for digital nomads and remote workers 🌎
