OwnerRez MCP Server

A Model Context Protocol server that connects OwnerRez to Claude (Cowork / Claude Desktop) and any other MCP client. Ask about bookings, see who's checked in, message guests, record expenses, and manage webhooks — in natural language. Built with Python + FastMCP.

⚠️ Community project, not affiliated with OwnerRez.

Quickstart

New here? QUICKSTART.md gets you to a working connection in two commands.

The fastest path — no clone, no venv — using uv:

This same server works in any MCP client — Claude, Cursor, Windsurf, VS Code, Cline, Zed, and more. Add the standard block below to your client's MCP config (QUICKSTART.md lists each client's config file location and the few that use a different key):

{
  "mcpServers": {
    "ownerrez": {
      "command": "uvx",
      // Before a PyPI release, run straight from GitHub:
      "args": ["--from", "git+https://github.com/buildwithmanag/ownerrez-mcp", "ownerrez-mcp"],
      // After `pip`/PyPI publish this becomes simply: "args": ["ownerrez-mcp"],
      "env": {
        "OWNERREZ_USERNAME": "you@example.com",
        "OWNERREZ_TOKEN": "your_personal_access_token"
      }
    }
  }
}

Restart your client and the OwnerRez tools appear. That's it.

Prefer to run from source? See Install from source.

What it can do

Tools

Tool	Purpose	Endpoint
list_bookings	Bookings changed since a time; filter by status / property / arrival window	GET /v2/bookings ✅
get_booking	Full detail for one booking	GET /v2/bookings/{id} ✅
who_is_staying	Who's checked in right now, per property	derived ✅
list_properties / list_owners / find_guest	Reference lookups	GET ✅
list_quotes / list_payments / list_refunds / list_fees	Financial reads	GET ✅
list_messages	Messages in a thread (by threadId)	GET /v2/messages ✅
send_message	Reply to a guest (write)	POST /v2/messages ✅
list_webhook_subscriptions	List webhooks	GET ✅
create_webhook_subscription / delete_webhook_subscription	Manage webhooks (write)	POST/DELETE ✅
list_open_messages / get_message_event / mark_message_handled	Inbound-message inbox, fed by the webhook receiver	local store ✅

Resources: ownerrez://properties, ownerrez://owners Prompts: draft_checkin_message, draft_guest_reply

Verified against the live API — two OwnerRez limitations to know: there is no public expense-creation endpoint, and no endpoint that lists message threads. Inbound guest messages arrive via webhooks — subscribe to the message category with create_webhook_subscription, then use the event's threadId with list_messages / send_message. Bookings and guests are bounded by a "since" time, not by stay dates.

Example prompts

• "Who's checking in this weekend?"
• "Who's currently staying at the Beach House?"
• "Draft a check-in message for the guest arriving tomorrow at Cabin 3."
• "Show me all payments on booking 84213."
• "List the messages on thread 55123 and draft a reply."

Authentication

Pick whichever fits — the server prefers OAuth if both are set.

Personal Access Token (simplest for one account). OwnerRez → Settings → API → Personal Access Tokens. Set OWNERREZ_USERNAME + OWNERREZ_TOKEN.

OAuth (for multi-account / distribution). Create an OAuth app in OwnerRez, set OWNERREZ_CLIENT_ID + OWNERREZ_CLIENT_SECRET, then run the built-in helper:

ownerrez-mcp auth

It opens the authorize page, captures the redirect locally, and prints the OWNERREZ_ACCESS_TOKEN to save.

Real inbound messages (webhook receiver)

OwnerRez has no endpoint to poll for open conversations — inbound guest messages are delivered by webhooks. This package ships a small receiver that captures them into a local store so list_open_messages becomes a real inbox.

# 1. Install the optional extra and run the receiver
pip install "ownerrez-mcp[webhook]"
ownerrez-mcp webhook                      # listens on 0.0.0.0:8000

# 2. Expose it on a public HTTPS URL (any tunnel works), e.g.
#    ngrok http 8000   ->   https://<something>.ngrok.app

Then register that URL (via the MCP tool or any client):

create_webhook_subscription(url="https://<something>.ngrok.app/", category="message")

Now incoming guest messages land in the store, and in your agent you can ask "show my open messages" (list_open_messages), reply with send_message using the message's thread_id, and mark_message_handled to clear it.

Config: OWNERREZ_STORE (db path, default ~/.ownerrez-mcp/messages.db), OWNERREZ_WEBHOOK_HOST / OWNERREZ_WEBHOOK_PORT, and an optional OWNERREZ_WEBHOOK_SECRET (sent as X-Webhook-Secret or ?secret=) to reject unauthenticated posts. Always run behind HTTPS.

Safety: read-only mode

Set OWNERREZ_READ_ONLY=1 to hard-block every write tool (messaging, expenses, webhook changes). Great for letting an assistant explore your data without any risk of it messaging a guest or mutating records.

Verify against the live API

ownerrez-mcp probe                 # read-only checks (safe)
ownerrez-mcp probe --probe-writes  # also tests the expense POST endpoint with
                                   # an invalid body (creates nothing)

The output tells you exactly which endpoints your token can reach and whether expense creation is WRITABLE or NOT SUPPORTED.

Install from source

git clone https://github.com/buildwithmanag/ownerrez-mcp
cd ownerrez-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # fill in your credentials
ownerrez-mcp probe     # sanity-check connectivity

Point your MCP client at the venv's executable:

{
  "mcpServers": {
    "ownerrez": {
      "command": "/path/to/ownerrez-mcp/.venv/bin/ownerrez-mcp",
      "env": { "OWNERREZ_ACCESS_TOKEN": "..." }
    }
  }
}

Configuration reference

Variable	Default	Purpose
OWNERREZ_ACCESS_TOKEN	—	OAuth access token (preferred)
OWNERREZ_USERNAME / OWNERREZ_TOKEN	—	Personal Access Token (Basic auth)
OWNERREZ_READ_ONLY	0	Block all write tools when truthy
OWNERREZ_MAX_RETRIES	3	Retries on 429/5xx
OWNERREZ_TIMEOUT	30	Request timeout (seconds)
OWNERREZ_BASE_URL	https://api.ownerrez.com/v2	API base URL
OWNERREZ_CLIENT_ID / OWNERREZ_CLIENT_SECRET	—	OAuth app creds (for auth)

Development

ruff check .   # lint
pytest         # tests

See CONTRIBUTING.md. Every tool returns a structured {"ok": ...} envelope, follows OwnerRez v2 pagination, redacts secrets from errors, and retries transient failures.

License

MIT — see LICENSE. API reference: https://api.ownerrez.com/help/v2