guesty-mcp-server 0.3.0

package/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.git
+.env
+.token-cache.json
+*.md
+LICENSE

package/.env.example

@@ -0,0 +1,2 @@
+GUESTY_CLIENT_ID=your-client-id-here
+GUESTY_CLIENT_SECRET=your-client-secret-here

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to the Guesty MCP Server will be documented in this file.
+
+## [0.2.0] - 2026-03-26
+
+### Added
+- `create_reservation` - Create direct bookings (website → Guesty)
+- `get_reviews` - Fetch guest reviews from all channels
+- `get_calendar` - Check availability and pricing by date range
+- `update_calendar` - Block/unblock dates, set minimum nights
+- `respond_to_review` - Post responses to guest reviews
+- `get_owner_statements` - Owner revenue statements and reports
+- `get_expenses` - Track operational expenses
+- `get_channels` - List connected booking channels per property
+- `get_tasks` - Fetch cleaning and maintenance tasks
+- Rate limit retry with exponential backoff
+- Token caching module
+
+## [0.1.0] - 2026-03-26
+
+### Added
+- Initial release with 6 core tools
+- `get_reservations` - Fetch reservations with date/listing/status filters
+- `get_listing` - Get property details or list all properties
+- `get_conversations` - Fetch guest message history
+- `send_guest_message` - Send messages to guests in conversations
+- `get_financials` - Revenue, payouts, and commission data
+- `update_pricing` - Update base price or date-specific pricing
+- OAuth2 authentication with automatic token refresh
+- CONTRIBUTING.md for open source contributors
+- MIT License

package/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to Guesty MCP Server
+
+Thank you for your interest in contributing! This is the first MCP server for property management, and community contributions help make it better for everyone.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/guesty-mcp-server.git`
+3. Install dependencies: `npm install`
+4. Create a `.env` file with your Guesty API credentials (see `.env.example`)
+5. Run the server: `npm start`
+
+## Adding New Tools
+
+Each tool wraps a Guesty API endpoint. To add a new tool:
+
+1. Identify the Guesty API endpoint from [Guesty Open API docs](https://open-api.guesty.com/api-docs)
+2. Add the tool in `src/server.js` using the `server.tool()` pattern
+3. Follow the existing naming convention: `verb_noun` (e.g., `get_reservations`, `update_pricing`)
+4. Include proper Zod schema validation for all parameters
+5. Return structured JSON in the response
+
+### Tool Template
+
+```javascript
+server.tool(
+  "tool_name",
+  "Clear description of what this tool does",
+  {
+    param1: z.string().describe("What this parameter does"),
+    param2: z.number().optional().describe("Optional parameter"),
+  },
+  async (params) => {
+    const data = await guestyGet("/endpoint", { key: params.param1 });
+    return {
+      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+  }
+);
+```
+
+## Desired Contributions
+
+We'd love help with:
+- **New tools**: Reviews management, task/cleaning scheduling, owner statements, channel management
+- **Testing**: Integration tests, error handling edge cases
+- **Documentation**: Usage examples, video tutorials, blog posts
+- **PMS integrations**: Adapting this pattern for Hostaway, Lodgify, OwnerRez, etc.
+
+## Code Style
+
+- ES modules (import/export)
+- Async/await for all API calls
+- Descriptive error messages
+- Keep tools focused -- one API action per tool
+
+## Pull Requests
+
+1. Create a feature branch: `git checkout -b feature/new-tool`
+2. Make your changes
+3. Test against the Guesty API
+4. Submit a PR with a clear description of what the tool does and why
+
+## Questions?
+
+Open an issue on GitHub or reach out to [DLJ Properties](https://tinyhomeboutiques.com).

package/Dockerfile

@@ -0,0 +1,13 @@
+FROM node:18-alpine
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+
+ENV GUESTY_CLIENT_ID=""
+ENV GUESTY_CLIENT_SECRET=""
+
+EXPOSE 3001 3002
+
+CMD ["node", "src/server.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DLJ Properties
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# Guesty MCP Server
+
+The first MCP (Model Context Protocol) server for [Guesty](https://guesty.com) property management. Connect AI agents directly to your Guesty account to manage reservations, communicate with guests, track finances, and update pricing -- all autonomously.
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `get_reservations` | Fetch reservations with filters (dates, listing, status, guest) |
+| `get_listing` | Get property details or list all properties |
+| `get_conversations` | Fetch guest message history |
+| `send_guest_message` | Send messages to guests in conversations |
+| `get_financials` | Revenue, payouts, and commission data |
+| `update_pricing` | Update base price or date-specific pricing |
+| `create_reservation` | Create direct bookings (website → Guesty) |
+| `get_reviews` | Fetch guest reviews from all channels |
+| `get_calendar` | Check availability and pricing by date |
+| `update_calendar` | Block/unblock dates, set minimum nights |
+| `respond_to_review` | Post responses to guest reviews |
+| `get_owner_statements` | Owner revenue statements and reports |
+| `get_expenses` | Track operational expenses |
+| `get_channels` | List connected booking channels per property |
+| `get_tasks` | Fetch cleaning and maintenance tasks |
+
+## Quick Start
+
+### 1. Get Guesty API Credentials
+
+1. Log into [Guesty Dashboard](https://app.guesty.com)
+2. Go to **Settings > API** (or Marketplace > API Credentials)
+3. Create an API application with `open-api` scope
+4. Copy your **Client ID** and **Client Secret**
+
+### 2. Install
+
+```bash
+git clone https://github.com/DLJRealty/guesty-mcp-server.git
+cd guesty-mcp-server
+npm install
+```
+
+### 3. Configure
+
+Set your Guesty credentials as environment variables:
+
+```bash
+export GUESTY_CLIENT_ID="your-client-id"
+export GUESTY_CLIENT_SECRET="your-client-secret"
+```
+
+### 4. Add to Claude Code
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "guesty": {
+      "command": "node",
+      "args": ["/path/to/guesty-mcp-server/src/server.js"],
+      "env": {
+        "GUESTY_CLIENT_ID": "your-client-id",
+        "GUESTY_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+### 5. Use
+
+Once connected, your AI agent can:
+
+```
+"Show me all reservations checking in this week"
+"What's the total revenue for March?"
+"Send a welcome message to the guest checking in tomorrow"
+"Update the base price for Unit Y to $159"
+"List all my properties with their current status"
+```
+
+## Use Cases
+
+- **Guest Communication**: AI agents auto-respond to guest inquiries using real reservation data
+- **Revenue Management**: Pull financial reports, analyze occupancy, optimize pricing
+- **Operations**: Track check-ins/outs, coordinate cleaning schedules, manage availability
+- **Marketing**: Identify low-occupancy periods, create targeted promotions
+- **Multi-Agent Teams**: Give your entire AI team (CEO, Marketing, CS, Ops) access to property data
+
+## Requirements
+
+- Node.js 18+
+- Guesty account with API access (Professional plan or higher)
+- MCP-compatible AI client (Claude Code, OpenClaw, etc.)
+
+## API Reference
+
+This server wraps the [Guesty Open API](https://open-api.guesty.com/api-docs). Authentication uses OAuth2 client credentials flow with automatic token caching and refresh.
+
+## Built By
+
+[DLJ Properties](https://tinyhomeboutiques.com) -- Running 7 properties with a fully autonomous AI agent team. Built for our own use, shared with the STR community.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security
+
+## API Credentials
+
+**Never commit API credentials to version control.**
+
+- Store `GUESTY_CLIENT_ID` and `GUESTY_CLIENT_SECRET` as environment variables
+- Use `.env` files locally (already in `.gitignore`)
+- Use secrets management in production (Docker secrets, AWS SSM, etc.)
+
+## Token Handling
+
+- OAuth2 tokens are cached in memory with automatic refresh
+- Tokens expire after 24 hours
+- Token cache file (`.token-cache.json`) is gitignored
+
+## API Access
+
+- The server uses OAuth2 client credentials flow
+- All API calls go through HTTPS
+- Rate limiting is handled with automatic retry
+
+## Reporting Vulnerabilities
+
+If you discover a security vulnerability, please email dljrealty@yahoo.com rather than opening a public issue.

package/docs/multi-account-design.md

@@ -0,0 +1,32 @@
+# Multi-Account Support Design (v3)
+
+## Overview
+Support managing multiple Guesty accounts from a single MCP server instance.
+
+## Configuration
+```json
+{
+  "accounts": {
+    "default": { "clientId": "xxx", "clientSecret": "xxx", "label": "DLJ Properties" },
+    "client-abc": { "clientId": "yyy", "clientSecret": "yyy", "label": "ABC Vacation Rentals" }
+  }
+}
+```
+
+## Usage
+Every tool accepts optional `accountId`:
+```
+get_reservations({ accountId: "client-abc", limit: 10 })
+```
+
+## Key Features
+- Separate token cache per account
+- Independent rate limit tracking
+- Per-account health checks
+- No cross-account data leakage
+- Audit log per account
+
+## Enterprise Use Cases
+- Property management companies with regional accounts
+- White-label SaaS serving multiple clients
+- Multi-brand hospitality groups

package/examples/claude-code-config.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "guesty": {
+      "command": "node",
+      "args": ["/path/to/guesty-mcp-server/src/server.js"],
+      "env": {
+        "GUESTY_CLIENT_ID": "your-client-id",
+        "GUESTY_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}

package/examples/docker-compose.yml

@@ -0,0 +1,13 @@
+version: '3.8'
+services:
+  guesty-mcp:
+    build: .
+    environment:
+      - GUESTY_CLIENT_ID=${GUESTY_CLIENT_ID}
+      - GUESTY_CLIENT_SECRET=${GUESTY_CLIENT_SECRET}
+      - WEBHOOK_PORT=3001
+      - MCP_HTTP_PORT=3002
+    ports:
+      - "3001:3001"
+      - "3002:3002"
+    restart: unless-stopped

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "guesty-mcp-server",
+  "version": "0.3.0",
+  "description": "MCP Server for Guesty Property Management - The first Guesty MCP server",
+  "main": "src/server.js",
+  "bin": {
+    "guesty-mcp-server": "src/server.js",
+    "guesty-cli": "src/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node tests/test-tools.js"
+  },
+  "keywords": [
+    "mcp",
+    "guesty",
+    "property-management",
+    "short-term-rental",
+    "airbnb",
+    "ai-agent"
+  ],
+  "author": "DLJ Properties",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DLJRealty/guesty-mcp-server.git"
+  },
+  "homepage": "https://github.com/DLJRealty/guesty-mcp-server",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Guesty CLI - Command line tool for quick Guesty queries
+ * Usage: guesty-cli <command> [options]
+ */
+
+const GUESTY_CLIENT_ID = process.env.GUESTY_CLIENT_ID;
+const GUESTY_CLIENT_SECRET = process.env.GUESTY_CLIENT_SECRET;
+
+if (!GUESTY_CLIENT_ID || !GUESTY_CLIENT_SECRET) {
+  console.error("Set GUESTY_CLIENT_ID and GUESTY_CLIENT_SECRET environment variables.");
+  process.exit(1);
+}
+
+let token = null;
+
+async function auth() {
+  const res = await fetch("https://open-api.guesty.com/oauth2/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "client_credentials", scope: "open-api",
+      client_id: GUESTY_CLIENT_ID, client_secret: GUESTY_CLIENT_SECRET,
+    }),
+  });
+  const d = await res.json();
+  if (!d.access_token) throw new Error("Auth failed");
+  token = d.access_token;
+}
+
+async function api(path) {
+  const res = await fetch(`https://open-api.guesty.com/v1${path}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) throw new Error(`API ${res.status}`);
+  return res.json();
+}
+
+const commands = {
+  reservations: async () => {
+    const d = await api("/reservations?limit=10&sort=checkIn&order=desc");
+    console.log(`\nUpcoming Reservations (${d.count} total):\n`);
+    for (const r of d.results || []) {
+      const guest = r.guest?.fullName || "Unknown";
+      const dates = `${r.checkIn?.slice(0,10)} → ${r.checkOut?.slice(0,10)}`;
+      const listing = r.listing?.title?.slice(0,35) || "?";
+      console.log(`  ${guest.padEnd(20)} | ${dates} | ${listing}`);
+    }
+  },
+  listings: async () => {
+    const d = await api("/listings?limit=25");
+    console.log(`\nProperties (${d.count} total):\n`);
+    for (const l of d.results || []) {
+      const status = l.active ? "ACTIVE" : "OFF";
+      console.log(`  ${(l.nickname||"?").padEnd(25)} | ${status.padEnd(6)} | ${l.title?.slice(0,40)}`);
+    }
+  },
+  revenue: async () => {
+    const d = await api("/reservations?limit=100&fields=money%20guest%20checkIn%20listing%20status");
+    let total = 0;
+    for (const r of d.results || []) total += r.money?.totalPaid || 0;
+    console.log(`\nRevenue Summary:\n  Reservations: ${d.count}\n  Total Revenue: $${total.toLocaleString()}`);
+  },
+  reviews: async () => {
+    const d = await api("/reviews?limit=5");
+    console.log(`\nRecent Reviews (${d.count} total):\n`);
+    for (const r of d.results || []) {
+      console.log(`  ⭐ ${r.rating}/5 | ${r.guest?.fullName || "?"} | ${r.comment?.slice(0,60) || ""}`);
+    }
+  },
+  help: () => {
+    console.log(`
+Guesty CLI - Quick property management queries
+
+Commands:
+  reservations  Show upcoming reservations
+  listings      List all properties
+  revenue       Revenue summary
+  reviews       Recent guest reviews
+  help          Show this help
+
+Usage: GUESTY_CLIENT_ID=xxx GUESTY_CLIENT_SECRET=xxx node src/cli.js <command>
+    `);
+  },
+};
+
+const cmd = process.argv[2] || "help";
+if (!commands[cmd]) {
+  console.error(`Unknown command: ${cmd}. Run with 'help' for options.`);
+  process.exit(1);
+}
+
+(async () => {
+  try {
+    if (cmd !== "help") await auth();
+    await commands[cmd]();
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+})();

package/src/health.js

@@ -0,0 +1,43 @@
+import { createServer } from "http";
+
+const startTime = Date.now();
+const HEALTH_PORT = parseInt(process.env.HEALTH_PORT || "3003", 10);
+
+export function startHealthCheck(guestyAuthFn) {
+  const server = createServer(async (req, res) => {
+    if (req.url !== "/health" && req.url !== "/") {
+      res.writeHead(404);
+      res.end("Not Found");
+      return;
+    }
+
+    const uptime = Math.floor((Date.now() - startTime) / 1000);
+    let guestyStatus = "unknown";
+
+    try {
+      await guestyAuthFn();
+      guestyStatus = "connected";
+    } catch (e) {
+      guestyStatus = `error: ${e.message}`;
+    }
+
+    const health = {
+      status: guestyStatus === "connected" ? "healthy" : "degraded",
+      uptime: `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m ${uptime % 60}s`,
+      guestyApi: guestyStatus,
+      toolCount: 15,
+      version: "0.2.0",
+      transport: "stdio",
+      timestamp: new Date().toISOString(),
+    };
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(health, null, 2));
+  });
+
+  server.listen(HEALTH_PORT, () => {
+    console.log(`[health] Health check endpoint at http://localhost:${HEALTH_PORT}/health`);
+  });
+
+  return server;
+}

package/src/http-transport.js

@@ -0,0 +1,50 @@
+import { createServer } from "http";
+
+/**
+ * Streamable HTTP Transport for Guesty MCP Server
+ * Allows the MCP server to be accessed via HTTP instead of stdio.
+ * Useful for remote access, web integrations, and multi-client setups.
+ */
+
+const HTTP_PORT = parseInt(process.env.MCP_HTTP_PORT || "3002", 10);
+
+export function startHttpTransport(server) {
+  const httpServer = createServer(async (req, res) => {
+    // CORS headers
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    if (req.method !== "POST" || req.url !== "/mcp") {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Use POST /mcp" }));
+      return;
+    }
+
+    let body = "";
+    for await (const chunk of req) body += chunk;
+
+    try {
+      const request = JSON.parse(body);
+      // Forward to MCP server and get response
+      // This is a simplified passthrough -- full SSE streaming would need more work
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ received: true, request }));
+    } catch (e) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: e.message }));
+    }
+  });
+
+  httpServer.listen(HTTP_PORT, () => {
+    console.log(`[http] MCP HTTP transport listening on port ${HTTP_PORT}`);
+  });
+
+  return httpServer;
+}