Skip to main content
Glama

hostaway-mcp

Read-only, hospitality-shaped MCP server for Hostaway.

This repo owns the operator product only: local/npm stdio, six read-only tools, no Cloudflare Worker, and no Seascape booking surface.

V1 Goal

Make Codex and Claude useful in real Hostaway workflows without hand-wiring raw API calls every time.

V1 is intentionally narrow:

  • read-only only

  • hospitality-native tools, not raw endpoint parity

  • optimized for conversation context, reservation lookup, and listing lookup

Related MCP server: cloudbeds-mcp-server

Exact V1 Surface

  • list_unread_guest_threads

  • get_conversation_context

  • get_reservation_brief

  • get_listing_brief

  • search_reservations

  • search_conversations

Local Development

npm install
npm test
npm run check
npm run build

Run the stdio server locally:

HOSTAWAY_API_TOKEN=your-token-here node dist/cli.js

Create a local npm package tarball:

npm pack

After publish, run without cloning:

npx hostaway-mcp

MCP Client Wiring

For local MCP clients, provide HOSTAWAY_API_TOKEN through the environment and spawn the published npm package over stdio.

The snippets below are pinned to the current published version:

hostaway-mcp@0.2.0

Update that version intentionally when you upgrade.

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json.

If you already have top-level keys like preferences, keep them and add mcpServers alongside them:

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "hostaway-mcp@0.2.0"],
      "env": {
        "HOSTAWAY_API_TOKEN": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop after saving the file.

Codex

Edit ~/.codex/config.toml and add:

[mcp_servers.hostaway]
command = "npx"
args = ["-y", "hostaway-mcp@0.2.0"]

[mcp_servers.hostaway.env]
HOSTAWAY_API_TOKEN = "your-token-here"

Verify the server is registered:

codex mcp list

Local Built CLI

If you want to run the repo checkout instead of npm, point the client at the built CLI directly:

{
  "command": "node",
  "args": ["/absolute/path/to/hostaway-mcp/dist/cli.js"],
  "env": {
    "HOSTAWAY_API_TOKEN": "your-token-here"
  }
}

Environment Variables

Variable

Required

Default

Description

HOSTAWAY_API_TOKEN

Yes

—

Hostaway API token used to authenticate all requests.

HOSTAWAY_BASE_URL

No

Hostaway production URL

Override the API base URL (useful for testing).

V1 Non-Goals

  • sending guest messages

  • mutating reservations or listings

  • Cloudflare Worker transport

  • Seascape booking/distribution flows

  • webhook ingestion

  • background sync pipelines

  • dashboards or owner reporting

  • generic REST-to-MCP proxy coverage

Source Design

See docs/designs/v1-readonly-hostaway-mcp.md.

Available Tools

6 tools
get_conversation_contextC

Return an agent-friendly conversation summary plus recent message history.

Inputs: conversationId (required), detailLevel, messageLimit. Returns: raw, guest, notes, channel, +11 more

get_listing_briefC

Return the minimum useful listing context tied to conversations or reservations.

Inputs: listingId (required), detailLevel. Returns: raw, city, notes, country, +7 more

get_reservation_briefC

Return the minimum useful reservation context for an agent or operator.

Inputs: reservationId (required), detailLevel. Returns: raw, notes, status, channel, +9 more

list_unread_guest_threadsB

List recent guest threads with raw unread metadata and derived attention signals.

Inputs: limit, messageLimit. Returns: total, threads

search_conversationsC

Lookup conversations by guest name, listing, reservation id, or conversation id.

Inputs: conversationId, reservationId, guestName, listingId, +1 more. Returns: total, results

search_reservationsC

Lookup reservations by guest name, date range, listing, or reservation id.

Inputs: reservationId, guestName, guestEmail, listingId, +5 more. Returns: total, results

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 6 tools

    Disambiguation4/5

    Tools are generally well-differentiated by verb (get/search/list) and resource type. While conversation, listing, and reservation domains overlap in hospitality workflows, the tools specify distinct operations (retrieval by ID vs. filtered lists vs. search) that minimize selection errors.

    Naming Consistency4/5

    All tools follow a consistent snake_case verb_noun pattern with appropriate verbs (get, list, search). Minor deviation exists in noun choice: two tools use 'brief' while one uses 'context' for similar summary-retrieval purposes, slightly muddling the semantic pattern.

    Tool Count5/5

    Six tools represent a focused, appropriate scope for guest communication and reservation lookup functionality. The count sits in the ideal range for a specialized retrieval server, avoiding bloat while covering essential read operations.

    Completeness3/5

    The surface provides comprehensive read access to conversations, listings, and reservations but lacks write operations such as sending messages, creating reservations, or updating listing status. This read-only limitation creates notable gaps for agents attempting to actively resolve guest issues or modify bookings.

    Related MCP Connectors

    Related MCP Servers