{
  "markdown": "# hostaway-mcp\n\n[![npm version](https://img.shields.io/npm/v/@matt-long-plux/hostaway-mcp.svg)](https://www.npmjs.com/package/@matt-long-plux/hostaway-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)\n\nAn open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects AI assistants like Claude Desktop, Claude Code, and Cursor to the [Hostaway](https://www.hostaway.com) property management API. Query reservations, listings, calendars, financials, and guest conversations using natural language.\n\n## Quick Start\n\n1. Get your **Account ID** and **Client Secret** from your Hostaway dashboard under **Settings > API**\n2. Make sure you have **Node.js 18+** installed\n3. Pick your AI client below and add the config — no cloning or building required\n\n## Setup\n\n### Claude Desktop (Mac & Windows)\n\nOpen your Claude Desktop config file:\n\n- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAdd the following (merge with existing `mcpServers` if you have other servers configured):\n\n```json\n{\n  \"mcpServers\": {\n    \"hostaway\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@matt-long-plux/hostaway-mcp\"],\n      \"env\": {\n        \"HOSTAWAY_ACCOUNT_ID\": \"YOUR_ACCOUNT_ID\",\n        \"HOSTAWAY_CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop and you're ready to go.\n\n### Claude Code\n\n**Option 1 — CLI command (quickest):**\n\n```bash\nclaude mcp add hostaway \\\n  -e HOSTAWAY_ACCOUNT_ID=YOUR_ACCOUNT_ID \\\n  -e HOSTAWAY_CLIENT_SECRET=YOUR_CLIENT_SECRET \\\n  -- npx -y @matt-long-plux/hostaway-mcp\n```\n\n**Option 2 — `.mcp.json` in your project root** (good for sharing with teammates):\n\n```json\n{\n  \"mcpServers\": {\n    \"hostaway\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@matt-long-plux/hostaway-mcp\"],\n      \"env\": {\n        \"HOSTAWAY_ACCOUNT_ID\": \"YOUR_ACCOUNT_ID\",\n        \"HOSTAWAY_CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd the same config to your project's `.cursor/mcp.json`, or go to **Cursor Settings > MCP Servers > Add Server** and paste:\n\n```json\n{\n  \"mcpServers\": {\n    \"hostaway\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@matt-long-plux/hostaway-mcp\"],\n      \"env\": {\n        \"HOSTAWAY_ACCOUNT_ID\": \"YOUR_ACCOUNT_ID\",\n        \"HOSTAWAY_CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\"\n      }\n    }\n  }\n}\n```\n\n## Updating\n\nIf you installed a previous version via `npx`, your system may have a cached copy. To update to the latest release:\n\n```bash\nnpx clear-npx-cache\n```\n\nThen restart your AI client (Claude Desktop, Cursor, etc.). The next launch will automatically pull the latest version.\n\nAlternatively, you can pin `@latest` in your config to always fetch the newest version on each restart:\n\n```json\n\"args\": [\"-y\", \"@matt-long-plux/hostaway-mcp@latest\"]\n```\n\n## Tools Reference\n\n### Reservations\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `list_reservations` | List reservations with filters | `listingMapId`, `dateFrom`, `dateTo`, `status`, `channelId`, `limit` |\n| `get_reservation` | Get full reservation details | `reservationId` (required) |\n| `update_reservation_host_note` | Update internal host note | `reservationId`, `hostNote` (required) |\n| `list_reservations_by_property` | Current + upcoming reservations grouped by property | None |\n\n### Listings\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `list_listings` | All active listings with metadata | `includeArchived` |\n| `get_listing` | Full listing details | `listingId` (required) |\n| `get_listing_custom_fields` | Custom field values as name-value map | `listingId` (required) |\n\n### Calendar\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `get_calendar` | Availability and pricing calendar | `listingId`, `startDate`, `endDate` (all required) |\n| `get_gap_nights` | Find short unbooked gaps between reservations | `listingId` (required), `startDate`, `endDate`, `maxGapLength` |\n| `create_calendar_block` | Block dates on calendar | `listingId`, `startDate`, `endDate` (required), `note` |\n| `delete_calendar_block` | Remove a calendar block | `listingId`, `calendarBlockId` (required) |\n\n### Financials\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `get_reservation_financials` | Financial breakdown for a reservation | `reservationId` (required) |\n| `get_revenue_summary` | Aggregated revenue across listings | `dateFrom`, `dateTo` (required), `listingId` |\n| `get_payout_report` | Payout report for reconciliation | `dateFrom`, `dateTo` (required), `channelId` |\n\n### Conversations\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `list_conversations` | Recent guest conversations | `listingId`, `limit`, `unreadOnly` |\n| `get_conversation` | Full message thread | `conversationId` (required) |\n| `send_message` | Send message to guest | `conversationId`, `message` (required) |\n\n## Read-Only Mode\n\nSet `HOSTAWAY_READ_ONLY=true` to disable all write/mutation tools. When enabled, the following tools will return an error instead of executing:\n\n- `update_reservation_host_note`\n- `create_calendar_block`\n- `delete_calendar_block`\n- `send_message`\n\nThis is useful for shared accounts or when you want to prevent accidental modifications.\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `HOSTAWAY_ACCOUNT_ID` | Yes | Your Hostaway account ID (integer) |\n| `HOSTAWAY_CLIENT_SECRET` | Yes | Your Hostaway API client secret |\n| `HOSTAWAY_READ_ONLY` | No | Set to `true` to disable write operations |\n| `HOSTAWAY_CACHE_TTL` | No | Token cache TTL in seconds (default: 240) |\n\n## Example Queries\n\nOnce connected, try asking Claude:\n\n- \"Show me all upcoming reservations\"\n- \"What's the occupancy looking like for my properties next month?\"\n- \"Find gap nights across all listings for the next 90 days\"\n- \"How much revenue did I make last month?\"\n- \"Show me unread guest messages\"\n- \"What are the financials for reservation 12345?\"\n- \"Generate a payout report for Airbnb bookings in March\"\n\n## Contributing\n\nFeedback and pull requests are welcome! Please open an issue on [GitHub](https://github.com/mattlong-plux/hostaway-mcp/issues) or email [matt@plux.com](mailto:matt@plux.com).\n\n## License\n\nMIT\n",
  "bytes": 6556,
  "sha": "2dacc19fe9831323d4d027e9cf107eff3a94bb5462b4ee5629d698ceaa2d9386",
  "repo_slug": "mattlong-plux/hostaway-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mattlong_plux_hostaway_5a144329/readme"
}