Hostaway MCP server

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

Exact V1 Surface

• listunreadguest_threads
• getconversationcontext
• getreservationbrief
• getlistingbrief
• 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 HOSTAWAYAPITOKEN 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/claudedesktopconfig.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

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.