hostaway-mcp

@prosperkartik/hostaway-mcp

<p align="center"> <img src="./docs/hostaway-logo.png" alt="Hostaway" height="48" /> </p>

Model Context Protocol (MCP) server for the Hostaway PMS — connect Claude to your vacation rental ops.

@prosperkartik/hostaway-mcp connects Claude (in Claude Code, Claude Desktop, or any MCP-compatible client) to your Hostaway account — listings, reservations, calendar availability, guest messaging, and financials. Authored by an engineer who has integrated Hostaway, Ciirus, and major OTA APIs (Airbnb, VRBO, Booking.com, Expedia, Marriott) in production for short-term rental operators since 2022.

 

_Hostaway is a trademark of Hostaway Inc. This project is community-built and not affiliated with or endorsed by Hostaway._

Why this server

Three reasons:

1. Tool coverage. 10 read-only tools across listings, reservations, calendar, conversations, financials, and a health-check — broader surface than other community MCP servers in this space.
2. Cleaner auth UX. Takes the two credentials Hostaway gives you on the API settings page — Account ID + API Key — and handles the OAuth token exchange internally. No "go generate a bearer token elsewhere first" step.
3. Built by someone who works the API. The author has 3+ years of production Hostaway / Ciirus integration work behind the design decisions. Tools map to real operator workflows, not just REST endpoints.

Tools (v0.1)

All v0.1 tools are read-only. Write operations are coming in later versions, gated behind explicit confirmation.

| Tool | Description | |---|---| | whoami | Health-check — returns connected account counts (listings, reservations, conversations, owner statements, users). Run this first to confirm setup works. | | list_listings | List properties on the account | | get_listing | Full detail for a single listing — location, capacity, pricing, reputation, channel URLs | | list_reservations | List reservations, with optional filters by arrival date range and status | | get_reservation | Full detail for a single reservation — guest, dates, pricing, channel | | list_calendar | Per-day availability for a listing across a date range — answers "is property X free between A and B?" | | list_conversations | List guest message threads with unread state and last activity | | list_unread_conversations | Only conversations with unread guest messages — answers "who's waiting on a reply?" | | get_conversation_messages | Full message history of a single conversation | | list_owner_statements | List owner financial statements |

Quick start

1. Get your Hostaway API credentials

In your Hostaway operator account → Settings → Hostaway API. Generate API credentials. You'll get an Account ID and an API Key.

2. Add to Claude Code

claude mcp add hostaway \
  --scope user \
  -e HOSTAWAY_ACCOUNT_ID=your-account-id \
  -e HOSTAWAY_API_KEY=your-api-key \
  -- npx -y @prosperkartik/hostaway-mcp

(Or use --scope local to install for the current project only.)

3. Or add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add:

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "@prosperkartik/hostaway-mcp"],
      "env": {
        "HOSTAWAY_ACCOUNT_ID": "your-account-id",
        "HOSTAWAY_API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop. The Hostaway tools appear in the tools picker.

4. Try it

Ask Claude things like:

• "Run whoami to confirm Hostaway is connected."
• "List my Hostaway listings."
• "What reservations are checking in next week?"
• "Is listing 12345 available May 10–17?"
• "Do I have any unread guest messages?"
• "Show me the conversation with [guest]."

Example output (placeholder data)

> List my Hostaway listings.

Found 3 listings:

| ID    | Name              | Location          | Beds | Baths | Capacity | Status |
|-------|-------------------|-------------------|------|-------|----------|--------|
| 10001 | Sample Apt 2BR    | Sample City, US   | 2    | 2     | 4        | active |
| 10002 | Sample Loft       | Sample City, US   | 1    | 1     | 2        | active |
| 10003 | Sample Beachfront | Sample Beach, US  | 3    | 2     | 6        | active |

> Is listing 10001 available May 10–17?

# Calendar for listing 10001
8 days returned (2026-05-10 → 2026-05-17)  ·  6 available, 2 reserved, 0 blocked

| Date       | Available | Status   | Price | Min stay | Reserved | Blocked | Note |
|------------|-----------|----------|-------|----------|----------|---------|------|
| 2026-05-10 | ✓         | available| 220   | 2        | 0        | 0       |      |
| 2026-05-11 | ✓         | available| 220   | 2        | 0        | 0       |      |
| 2026-05-12 | ✗         | reserved | 220   | 2        | 1        | 0       |      |
| ...                                                                            |

Configuration

| Env var | Required | Description | |---|---|---| | HOSTAWAY_ACCOUNT_ID | yes | Your Hostaway account ID (acts as OAuth client_id) | | HOSTAWAY_API_KEY | yes | Your Hostaway API secret (acts as OAuth client_secret) |

The server exchanges those for a bearer token at startup and caches it in memory for the lifetime of the process.

Local development

git clone https://github.com/prosperkartik/hostaway-mcp.git
cd hostaway-mcp
npm install
cp .env.example .env  # fill in credentials
npm run build
npm start

Hot-reload via tsx:

npm run dev

Roadmap

• [x] v0.1 — 10 read-only tools across listings, reservations, calendar, conversations, financials, and health-check
• [ ] v0.2 — Tasks (list_tasks, get_task); Cancellation policies; Custom fields read
• [ ] v0.3 — Guest payments read; Webhooks read
• [ ] v0.4+ — Write operations (send guest messages, update calendar blocks, create tasks) gated behind explicit confirm: true

Have a request? Open an issue or start a discussion.

Security

• Credentials live in environment variables only — never written to disk by this server
• The bearer token lives in process memory; no persistent storage
• v0.1 is read-only end-to-end; nothing in this codebase can mutate Hostaway data
• For multi-property operators: the Hostaway API returns data scoped to the account whose credentials you supply, so cross-account access is not possible

Contributing

Issues and PRs welcome. The codebase is small and easy to read; start at src/index.ts.

License

MIT — see LICENSE.

Author

Built by Kartik Vats (@prosperkartik) — AI engineer at Kodeit. Three years of production work on PMS / OTA integrations and LLM tooling.

If you're a vacation rental operator or hospitality tech team and want help wiring AI into your ops, get in touch via kodeit.io or email prosperkartik@gmail.com.