🏡 Nomad Stays MCP Server

Find the perfect remote work accommodation worldwide

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

🔌 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/cost-estimate

Estimate the total cost for a stay duration and optional country.

durationDays (integer) Optional

Number of nights to estimate (default: 30)

Country code or country name to narrow the estimate

currency (string) Optional

Target currency for the estimate (e.g., EUR, USD)

checkInDate (string) Optional

Optional start date (e.g., 2026-05-15 or May)

Maximum number of sample stays to return (default: 15)

GET https://mcp.nomadstays.com/api/stays/cost-estimate?countrycode=ES&durationDays=30¤cy=EUR&limit=5

{ "countryCode": "ES", "durationDays": 30, "currency": "EUR", "estimatedCost": 1200, "sampleStays": [ ... ] }

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

1. Go to Settings → Features → Model Context Protocol
2. Click "Add Server"
3. Enter server URL: https://mcp.nomadstays.com/mcp
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/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)
getStayCostEstimate	Estimate total stay cost for a given duration and country without requiring a max budget	durationDays (optional, default 30), currency (optional), 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

💡 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"

Estimate stay cost for 1 month in Spain

curl "https://mcp.nomadstays.com/api/stays/cost-estimate?countrycode=ES&durationDays=30¤cy=EUR&limit=5"

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

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