Nomad Stays

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

🏡 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 NameDescriptionParameters
🔍 Search & Filter Tools
getStaysByCountrySearch stays by 2-letter country code or partial country namecountrycode (string), limit (number)
getStaysByContinentFilter stays by continent (Europe, Asia, Africa, etc.)continent (string), limit (number)
getStaysByLocationSearch across City, State, location name, country, and descriptionlocation (string), limit (number)
getStaysByLifestyleFind stays by lifestyle categorylifestyle (string), limit (number)
getStaysByBudgetSearch stays within budget and duration with FX conversiondurationDays, maxPrice, currency, countryCode (optional), checkInDate (optional), limit (optional)
getStaysByAmenitiesSearch stays by amenities with fuzzy matchingamenities (array), matchType (optional), minWifiSpeed (optional), limit (optional)
getStayByIDGet detailed information about a specific stayid (number)
📅 Availability & Booking Tools
checkStayAvailabilityCheck room availability for specific datesstayId, checkIn, checkOut, roomType (optional)
findNearestAvailabilityFind nearest available dates near preferred check-instayId, preferredCheckIn, minLengthOfStay, maxLengthOfStay (optional), searchWindowDays (optional)
getAvailabilityByMonthGet availability calendar for a specific monthstayId, year, month, minLengthOfStay
getRoomAvailabilityCheck availability for a specific roomroomId, checkIn, checkOut
📚 Reference & Metadata Tools
getAllLifestylesRetrieve all available lifestyle categoriesNone
getAllAmenitiesRetrieve all available amenities in the systemNone
getRoomAmenitiesGet amenities for a specific roomroomId

📊 Data Model

Stay Object

FieldTypeDescription
idstringUnique identifier for the stay
namestringName of the accommodation
descriptionstringShort description of the stay
countrystringFull country name
countryCodestringISO 3166-1 alpha-2 country code
citystringCity name
priceRangestringWeekly price range (e.g., "From EUR 250 per week")
priceCurrencystringCurrency code (e.g., EUR, USD)
amenitiesarrayList of available amenities
WiFiDownloadSpeednumberWiFi download speed in Mbps (optional)
WiFiUploadSpeednumberWiFi upload speed in Mbps (optional)
location_namestringLocation name from Location table
location_countrystringLocation country from Location table
PetsAllowedbooleanWhether pets are allowed
coordinatesobjectGeoLat and GeoLng coordinates
bookingUrlstringURL 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 🌎

Related Servers