Content
# @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.
[](https://www.npmjs.com/package/@prosperkartik/hostaway-mcp)
[](./LICENSE)
> _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
```bash
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:
```json
{
"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
```bash
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`:
```bash
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](https://github.com/prosperkartik/hostaway-mcp/issues) or [start a discussion](https://github.com/prosperkartik/hostaway-mcp/discussions).
## 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`](./src/index.ts).
## License
MIT — see [LICENSE](./LICENSE).
## Author
Built by **[Kartik Vats](https://kodeit.io)** ([@prosperkartik](https://github.com/prosperkartik)) — AI engineer at [Kodeit](https://kodeit.io). 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](https://kodeit.io) or email **prosperkartik@gmail.com**.
