{
  "markdown": "# Guesty MCP Server\n\n[![npm version](https://img.shields.io/npm/v/guesty-mcp-server)](https://www.npmjs.com/package/guesty-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThe first MCP (Model Context Protocol) server for [Guesty](https://guesty.com) property management. Connect any MCP-compatible AI client (Claude, ChatGPT, Copilot, Cline) to your Guesty account — manage reservations, communicate with guests, track finances, update pricing.\n\n**Live now:** all 43 tools, free — reservations, listings, guests, calendars, guest messaging, financial reports, pricing and listing writes, operations, reviews, webhooks, and IoT/property-health. No license key, no paid tier.\n\n**Why MCP:** Guesty is one of the larger PMS platforms in the short-term-rental space and no MCP integration existed. Every major PMS will need one — we built the first.\n\n**Built in production** on 10 of our own short-term rentals. Node.js + MCP SDK + Express, MIT licensed. Things we learned: Guesty's `/reservations` endpoint only returns future data (we use the calendar endpoint for historical), and the SSE transport doesn't run on Vercel serverless (expected). **The first and only MCP server for Guesty — all 43 tools free.**\n\nFull tool surface: **43 tools registered, all free** — 42 Guesty tools (23 read-only, 15 write/guest-messaging including `get_conversations`, and 4 IoT/property-health) plus `get_license_info`, which reports this server's own licensing state and makes no Guesty API call. **There are no paid tiers.** `GUESTY_MCP_LICENSE_KEY` is optional and does not change what you can call.\n\n> **Want AI to handle your guest messages 24/7?** [Guesty Copilot](https://guestycopilot.com) -- AI guest management for Guesty hosts, built on this MCP server. Now in beta.\n\n> **Stay updated:** [Sign up for release notes and new tool announcements](https://guestycopilot.com#signup)\n\n> **Everything is free.** All 43 tools work with no license key. Paid-prefix keys are still recognized (they show up in `get_license_info`) but are not required and unlock nothing extra — there is nothing extra to unlock. Set or omit `GUESTY_MCP_LICENSE_KEY`; access is the same either way.\n\n## Quick Start\n\n```bash\nnpx guesty-mcp-server\n```\n\nOr add to your Claude Code settings (`~/.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"guesty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"guesty-mcp-server\"],\n      \"env\": {\n        \"GUESTY_CLIENT_ID\": \"your-client-id\",\n        \"GUESTY_CLIENT_SECRET\": \"your-client-secret\"\n      }\n    }\n  }\n}\n```\n\n## Get Guesty API Credentials\n\n1. Log into [Guesty Dashboard](https://app.guesty.com)\n2. Go to **Settings > API** (or Marketplace > API Credentials)\n3. Create an API application with `open-api` scope\n4. Copy your **Client ID** and **Client Secret**\n\n## All 43 Tools\n\n### Reservations & Guests\n| Tool | Description |\n|------|-------------|\n| `get_reservations` | Fetch reservations with filters (dates, listing, status, guest) |\n| `create_reservation` | Create direct bookings (website to Guesty) |\n| `update_reservation` | Update reservation status, dates, guest info, or add notes |\n| `search_reservations` | Search by guest name, email, or confirmation code |\n| `get_reservation_financials` | Detailed financial breakdown for a reservation |\n| `create_reservation_note` | Add internal notes to a reservation |\n| `get_guests` | Search guest database by name or email |\n| `get_guest_by_id` | Get detailed guest profile |\n\n### Listings & Calendar\n| Tool | Description |\n|------|-------------|\n| `get_listing` | Get property details or list all properties |\n| `update_listing` | Update title, description, amenities, min nights, max guests |\n| `get_calendar` | Check availability and pricing by date |\n| `update_calendar` | Block/unblock dates, set minimum nights |\n| `get_calendar_blocks` | Get blocked dates with reasons |\n| `get_listing_occupancy` | Calculate occupancy rate over a date range |\n| `get_photos` | Fetch listing photos with captions |\n| `update_photos` | Replace or reorder listing photos |\n\n### Messaging\n| Tool | Description |\n|------|-------------|\n| `get_conversations` | Fetch guest message history |\n| `send_guest_message` | Send messages to guests in conversations |\n\n### Financials & Pricing\n| Tool | Description |\n|------|-------------|\n| `get_financials` | Revenue, payouts, and commission data |\n| `update_pricing` | Update base price or date-specific pricing |\n| `get_listing_pricing` | Get base price, discounts, and fee details |\n| `update_listing_pricing` | Update base price, cleaning fee, discounts |\n| `get_owner_statements` | Owner revenue statements and reports |\n| `get_expenses` | Track operational expenses |\n| `create_expense` | Create new expense records |\n| `get_revenue_summary` | Aggregated revenue across all listings |\n\n### Operations\n| Tool | Description |\n|------|-------------|\n| `get_tasks` | Fetch cleaning and maintenance tasks |\n| `create_task` | Create cleaning or maintenance tasks |\n| `get_reviews` | Fetch guest reviews from all channels |\n| `respond_to_review` | Post responses to guest reviews |\n| `get_channels` | List connected booking channels per property |\n| `get_supported_languages` | Get supported languages for a listing |\n\n### Automation & Integrations\n| Tool | Description |\n|------|-------------|\n| `get_automation_rules` | List automation and workflow rules |\n| `get_webhooks` | List registered webhooks |\n| `create_webhook` | Register new webhook for event notifications |\n| `delete_webhook` | Remove a registered webhook |\n| `get_custom_fields` | Fetch custom fields for listings or reservations |\n| `get_account_info` | Get account info and subscription details |\n\n### Server & Licensing\n| Tool | Description |\n|------|-------------|\n| `get_license_info` | Report this MCP server's own licensing state — every tool is currently free; lists the tool ledger and whether a key was detected. Makes no Guesty API call. |\n\nIt is counted in the 43 registered tools but **not** in the \"42 Guesty tools\" figure, because it reports our licensing state rather than doing anything with your Guesty account: 42 Guesty tools + this one = 43.\n\n### IoT & Property Health\n| Tool | Description |\n|------|-------------|\n| `get_readiness_score` | Composite turnover-readiness score for a property from cleaning, maintenance, and IoT signals |\n| `get_property_health` | Aggregate health signal per property: reservation status, open maintenance alerts, review-score, last-clean timestamp, IoT hub status |\n| `submit_checkout_photos` | Accept post-checkout photo uploads and log them to the property's maintenance/cleaning record |\n| `get_maintenance_alerts` | List or filter open maintenance alerts for a property or portfolio |\n\nThese four tools are free like everything else. They read the local IoT database (`IOT_DB_PATH`) that the optional webhook receiver (`src/webhook/iot-receiver-server.js`) populates. With no devices reporting they return empty device and alert lists, a low readiness score that names each missing signal, and null IoT fields in the health snapshot — not errors — and the Guesty-side fields still fill in.\n\n## Use Cases\n\n- **Guest Communication**: guest-messaging tools draft and send replies grounded in real reservation data\n- **Revenue Management**: Pull financial reports, analyze occupancy, optimize pricing\n- **Operations**: Track check-ins/outs, coordinate cleaning schedules, manage availability\n- **Marketing**: Identify low-occupancy periods, create targeted promotions\n- **Connected Tools**: give every MCP-compatible client in your stack access to the same property data\n\n## Requirements\n\n- Node.js 18+\n- Guesty account with API access (Professional plan or higher)\n- MCP-compatible AI client (Claude Code, Cursor, Windsurf, etc.)\n\n## Environment Variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `GUESTY_CLIENT_ID` | — | OAuth2 client id (required) |\n| `GUESTY_CLIENT_SECRET` | — | OAuth2 client secret (required) |\n| `IOT_WEBHOOK_PORT` | `3100` | Port for the IoT webhook receiver stub (`src/webhook/iot-receiver-server.js`). Local/reverse-proxy only — do not expose publicly. Production requires a reverse proxy that terminates TLS and enforces real HMAC against `IOT_WEBHOOK_SECRET`. |\n\n## API Reference\n\nThis server wraps the [Guesty Open API](https://open-api.guesty.com/api-docs). Authentication uses OAuth2 client credentials flow with automatic token caching, retry logic, and rate limit handling.\n\n## Built By\n\n[DLJ Properties](https://tinyhomeboutiques.com) -- Battle-tested on our own 10-property STR portfolio. Built for our own use, shared with the STR community.\n\n## License\n\nMIT\n",
  "bytes": 8721,
  "sha": "2774d92a850faef49dcea5fe65faa4079f6504ed6c1d26c756da6c626a05ca6d",
  "repo_slug": "dljrealty/guesty-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dljrealty_guesty_41e1c523/readme"
}