{
  "markdown": "# NomadStays MCP Server\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI agents access to Nomad Stays accommodation data — search by country, continent, location, lifestyle, budget, amenities, and availability.\n\nCompatible with **Claude**, **ChatGPT**, and any MCP-aware AI agent.\n\n## Tools available\n\nFull, current tool list: 76 tools total. See [mcp.nomadstays.com](https://mcp.nomadstays.com) for the complete reference with parameters — this README lists them grouped by category; keep both in sync when tools are added or changed.\n\n### Search, availability, and reference (public, no auth)\n\n| Tool | Description |\n|---|---|\n| `getStaysByCountry` | Search stays by 2-letter country code or country name |\n| `getStaysByContinent` | Search by continent (Europe, Asia, Africa, etc.) |\n| `getStaysByLocation` | Free-text search across city, region, location description |\n| `getStaysByLifestyle` | Filter by lifestyle category (Digital Nomad, Beach, City…) |\n| `getStaysByBudget` | Find stays within a budget for a given duration and currency |\n| `getStaysByAmenities` | Filter by amenities (WiFi, Pool, Air Conditioning…) |\n| `getStaysByWiFiSpeed` | Filter by minimum WiFi download speed (Mbps) |\n| `getStayByID` | Full details for a single stay |\n| `getAllLifestyles` | List all available lifestyle categories |\n| `getAllAmenities` | List all available amenities |\n| `checkStayAvailability` | Check if a stay is available for given dates |\n| `findNearestAvailability` | Find nearest available dates when preferred dates are taken |\n| `getAvailabilityByMonth` | All available windows in a specific month |\n| `getRoomAvailability` | Per-room availability for a date range |\n| `getRoomAmenities` | Full amenity list for a specific room including WiFi metrics |\n| `searchHelpCenter` | Search Nomad Stays help centre articles |\n| `getHelpCenterArticle` | Fetch a specific help article by ID |\n| `listHelpCenterCategories` | List all help centre categories |\n\n### Account signup for AI agents\n\nIf the person you're assisting doesn't have a Nomad Stays account yet, use the `signupNomadStaysAccount` tool to create one for them — no authentication, browser, or CAPTCHA required.\n\n| Tool | Description |\n|---|---|\n| `signupNomadStaysAccount` | Create a new Nomad Stays account for someone who doesn't have one yet. Returns `pending_email_confirmation` — no session or token. |\n\nNotes:\n\n- The account is created but **inactive** until the human clicks the confirmation link emailed to them — no session or token is returned by this call, and the agent cannot sign in or act as the user itself. This is the trust boundary: it proves a real inbox exists behind the request, standing in for the CAPTCHA/honeypot checks the public browser signup form uses instead.\n- Rate-limited to 2 requests per 5 minutes per source IP, server-side (`Controllers/AgentSignupApiController.cs` in the main repo).\n- Once the human confirms their email and logs in normally at `www.nomadstays.com/Account/Login`, they can request an MCP bearer token or complete OAuth (see \"Trusted Stay Partner management tools\" below) to let their own agent act on their behalf going forward.\n\n### Product, purchase, and application tools (require an MCP agent token)\n\nStay, Experience, and Coworking applications each go through the same `list` / `get` / `create` / `save` / `submit` lifecycle. Stay and Experience applications carry a one-time EUR 39 Application Fee (products 8 and 9); Coworking applications have no fee.\n\n| Tool | Description |\n|---|---|\n| `getProductInfo` | Look up a product's price and purchasability (product 8 = Stay Application, 9 = Experience Application) |\n| `purchaseProduct` | Start a purchase on the caller's own behalf; returns a `checkoutUrl` or resolves as \"waived\" |\n| `getPurchaseStatus` | Check whether a purchase has been paid, verified fresh against the payment provider |\n| `listStayApplications` / `getStayApplication` / `createStayApplication` / `saveStayApplication` / `submitStayApplication` | Full Stay Application lifecycle |\n| `listExperienceApplications` / `getExperienceApplication` / `createExperienceApplication` / `saveExperienceApplication` / `submitExperienceApplication` | Full Experience Application lifecycle (min. 4-day experiences, enforced server-side) |\n| `listCoworkingApplications` / `getCoworkingApplication` / `createCoworkingApplication` / `saveCoworkingApplication` / `submitCoworkingApplication` | Full Coworking Application lifecycle — no Application Fee |\n\n### Booking (require an MCP agent token)\n\n| Tool | Description |\n|---|---|\n| `quoteStayBooking` | Price a prospective booking (package, dates, guests) before committing |\n| `bookStay` | Create a booking on the caller's own behalf; returns a `checkoutUrl` or resolves as confirmed |\n| `getBookingStatus` | Check whether a booking is confirmed, verified fresh against the payment provider |\n| `listMyBookings` | List the caller's own bookings, including `needsAction`/`checkoutUrl` for anything still pending |\n\n## Trusted Stay Partner management tools\n\nThe tools above are read-only and public (aside from applications, which are self-service but still token-gated). A separate set of tools lets an **authorized Trusted Stay Partner's own AI agent** read AND write their own listing data — with the same capabilities (no more, no less) as they have via the Nomad Stays admin UI. These require a bearer token issued from the partner's Operator Information page at `www.nomadstays.com/stayadmin/user-profile-stays` (2FA must be enabled on the account to request one), set as `NOMADSTAYS_MCP_AGENT_TOKEN`. Every call is scoped server-side to Stays the authenticated account actually owns.\n\n| Tool | Description |\n|---|---|\n| `getMyStays` / `getMyStayDetail` / `updateStayDetail` | Read/update a Stay's core details (title, description, address, policies) |\n| `getMyStayOnboardingStatus` | The six \"Listing Completion\" scores from the Stay dashboard (Stay Details, Availability, Rooms, Packages, Wi-Fi, Operator Information) plus an overall percentage — Wi-Fi is a test-freshness score, not a speed rating |\n| `getMyStayRooms` / `createStayRoom` / `updateStayRoom` / `deleteStayRoom` | Full room CRUD, including bed sizes, facilities, and photos |\n| `getRoomTypeOptions` / `getRoomFacilityOptions` | Reference lookups for valid room types/facilities (differ for boutique vs standard Stays) |\n| `uploadStayPhoto` / `getMyStayPhotos` / `deleteStayPhoto` / `reorderStayPhotos` | Stay-level photo management, including reordering |\n| `deleteRoomPhoto` / `reorderRoomPhotos` | Room-level photo management |\n| `getMyStayPackages` / `createStayPackage` / `updateStayPackage` / `deleteStayPackage` | Pricing package CRUD — `sellPrice` is always server-computed, never directly settable |\n| `getCurrencyOptions` / `getBusinessModelOptions` | Reference lookups for package currency and business model |\n| `getMyStayOrganisationalData` / `updateStayOrganisationalData` | Address, check-in/out policy, cancellation policy, pets/children/parking rules |\n| `getStayTypeOptions` / `getCountryOptions` / `getCancellationPolicyOptions` / `getAdditionalInformationOptions` | Reference lookups for organisational-data fields |\n| `getMyStayContacts` / `updateStayContacts` | Public-facing contact details |\n| `getMyStayFacilities` / `updateStayFacilities` / `getFacilityGroups` | Facility checkboxes, grouped exactly as on the admin UI |\n| `getMyBusinessProfile` / `updateHostBusinessProfile` | Business profile (excludes personal, bank, and tax fields — never exposed via MCP) |\n\nKey rules: boutique Stays (`Boutique1`–`Boutique6` room types) and standard Stays are validated separately — always call `getRoomTypeOptions` first. Package price tiers are locked to 7/14/21/30 nights and don't all need to be set — a subset (e.g. 1-week-only) is valid. `advertisingEndpoint` only applies to Advertising-business-model Stays. Personal, bank, and tax details are permanently excluded from every tool.\n\n## Setup\n\n### 1. Prerequisites\n\n- Node.js 20+\n- Access to a Nomad Stays SQL Server database (hosted on Coolify/Hetzner)\n\n### 2. Install\n\n```bash\ngit clone https://github.com/nomadstays/nomadstays-mcp-server.git\ncd nomadstays-mcp-server\nnpm install\n```\n\n### 3. Configure\n\n```bash\ncp .env.example .env\n# Edit .env and set your NOMADSTAYS_DB_CONNECTION string\n```\n\n### 4. Build\n\n```bash\nnpm run build\n```\n\n### 5. Run (stdio mode — for Claude Desktop / local MCP clients)\n\n```bash\nnode build/index.js\n```\n\n### 6. Run (HTTP mode — for hosted / remote deployments)\n\n```bash\nPORT=8080 node build/index.js\n```\n\nHTTP endpoints:\n- `POST /mcp` — MCP Streamable HTTP transport\n- `GET /health` — Health check\n- `GET /api/mcp/stats/daily` — Daily usage stats\n- `GET /api/mcp/stats/tools` — Per-tool usage stats\n\n## Claude Desktop configuration\n\nCopy `claude_desktop_config.example.json`, update the path and connection string, then merge into your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nomadstays\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/nomadstays-mcp-server/build/index.js\"],\n      \"env\": {\n        \"NOMADSTAYS_DB_CONNECTION\": \"Server=tcp:...\"\n      }\n    }\n  }\n}\n```\n\n## Deploy\n\nThe production Nomad Stays deployment runs its MCP servers as Docker containers on **Coolify** (self-hosted on Hetzner) rather than Azure App Service. This repo doesn't include a Dockerfile of its own — containerize it with a standard Node.js build (Node 20+, `npm run build`, run `dist/index.js`) and deploy to any Docker-capable host, setting `NOMADSTAYS_DB_CONNECTION` (and `PORT`/`HTTP_PORT` for HTTP mode) as environment variables on the target platform.\n\n## Tech stack\n\n- TypeScript + Node.js 20\n- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)\n- Express (HTTP mode)\n- mssql (SQL Server connectivity)\n",
  "bytes": 9848,
  "sha": "324032cbe6cdc4a03cc9f80560c88f04fed093f974eb3d0f136906bff19995ea",
  "repo_slug": "nomadstays/nomadstays-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nomadstays_mcp_server_eb9a30c6/readme"
}