🏡 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/{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"\], "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:

Available Tools

Tool Name	Description	Parameters
🔍 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)
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

💡 Usage Examples

Find stays in Portugal

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

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"

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

• Contact: Contact Page

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