ownerrez-mcp-server

redblacktree/ownerrez-mcp-server

3.2

If you are the rightful owner of ownerrez-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The OwnerRez MCP Server is a Model Context Protocol server that facilitates interaction with the OwnerRez API v2.0 using OAuth2 authentication, enabling AI assistants to manage vacation rental data.

Tools
5
Resources
0
Prompts
0

OwnerRez MCP Server

A Model Context Protocol (MCP) server that provides access to the OwnerRez API v2.0 with OAuth2 authentication. This server enables AI assistants like Claude to interact with your OwnerRez vacation rental management data.

Features

  • Google OAuth Authentication: Secure user authentication via Google (OAuth 2.0 with dynamic client registration)
  • OwnerRez API Integration: Complete access to OwnerRez vacation rental management features
  • Dynamic Client Registration: MCP clients can register themselves automatically (RFC 7591)
  • Comprehensive API Coverage: 30+ tools covering all major OwnerRez API endpoints
  • Property Management: List, search, and retrieve property information
  • Booking Management: Create, update, and query bookings
  • Guest Management: Full CRUD operations for guest records
  • Quotes & Inquiries: Access quotes and inquiry data
  • Webhooks: Manage webhook subscriptions
  • Reviews & Listings: Access property reviews and listing content
  • Custom Fields & Tags: Manage tags and custom field definitions

Live Demo

A production instance of this MCP server is available at:

🌐 https://ownerrez-mcp-server.fly.dev

You can use this URL in your MCP client configuration instead of running your own server. See the MCP Client Configuration section for setup instructions.

Quick Start

Want to use the public server with an API key? Follow these 3 steps:

# 1. Clone this repo (just to use the CLI tool)
git clone https://github.com/redblacktree/ownerrez-mcp-server.git
cd ownerrez-mcp-server

# 2. Install dependencies
npm install

# 3. Generate your API key
npm run generate-api-key

The tool will open your browser for Google authentication, then generate and display your API key. Copy it and add to your MCP client config:

{
  "mcpServers": {
    "ownerrez": {
      "url": "https://ownerrez-mcp-server.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

That's it! No server setup required. See API Key Authentication for details.

Architecture Overview

This server implements two separate OAuth flows plus API key authentication:

Authentication to MCP Server (Choose One)

Option A: Google OAuth (User Authentication)
  • Identity Provider: Google
  • Purpose: Authenticate end users to this MCP server
  • Flow: MCP client → This server → Google → Back to MCP client
  • Dynamic Registration: MCP clients can register themselves without manual configuration
  • Endpoints: /oauth/register, /oauth/authorize, /oauth/token, /oauth/userinfo
  • Best for: Interactive use, automatic token refresh
Option B: API Keys (Simple Authentication)
  • Purpose: Authenticate users to this MCP server with a static token
  • Flow: User obtains API key via OAuth → Uses key as Bearer token in MCP client
  • Management: Self-service via /api/keys endpoints (requires OAuth to create)
  • Format: orz_<64-char-hex> (e.g., orz_a1b2c3d4...)
  • Best for: Automation, simpler setup, headless environments

OwnerRez Backend OAuth (API Authorization)

  • Identity Provider: OwnerRez
  • Purpose: Authorize access to OwnerRez API on behalf of users
  • Flow: User → OwnerRez → This server stores tokens
  • Endpoints: /api/connect/ownerrez/start, /api/connect/ownerrez/callback
  • Required: Both authentication methods require this step to access OwnerRez data

Important: Authentication to the MCP server (Google OAuth OR API key) is separate from authorization to access OwnerRez data (OwnerRez OAuth). Users must complete both steps to use OwnerRez tools.

Prerequisites

For Server Operators

  1. Google OAuth Application:

    • Create a project in Google Cloud Console
    • Enable Google+ API
    • Create OAuth 2.0 credentials (Web application)
    • Note your Client ID and Client Secret

  2. OwnerRez OAuth Application:

  3. Database: PostgreSQL database for storing OAuth sessions

  4. Node.js: Version 18 or higher

For End Users

  • A Google account (for authentication)
  • An OwnerRez account (to access property management features)
  • An MCP-compatible client (Claude Desktop, Cursor, etc.)

Installation

Option 1: Docker (Recommended for Local Development)

The easiest way to get started is using Docker for PostgreSQL:

# Clone the repository
git clone <repository-url>
cd ownerrez-mcp-server

# Copy environment file
cp env.example .env
# Edit .env and add your Google and OwnerRez OAuth credentials

# Start PostgreSQL in Docker
npm run docker:dev:up

# Install dependencies and run the app locally
npm install
npm run dev:http

Quick npm scripts:

  • npm run docker:dev:up - Start PostgreSQL
  • npm run docker:dev:down - Stop PostgreSQL
  • npm run docker:dev:reset - Reset database
  • npm run docker:dev:logs - View logs

See for detailed Docker instructions.

Option 2: Install from npm (Coming Soon)

npm install -g ownerrez-mcp-server

Option 3: Install from Source (Manual Setup)

# Clone the repository
git clone <repository-url>
cd ownerrez-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Set up PostgreSQL manually
# Create database: createdb ownerrez_mcp
# Update DATABASE_URL in .env

Configuration

1. Environment Variables

Copy the example environment file and customize it:

cp env.example .env

Edit .env with your credentials:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/ownerrez_mcp

# Google OAuth (for MCP client authentication - user login to this server)
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/callback

# OwnerRez OAuth (for backend API access - connecting OwnerRez accounts)
OWNERREZ_CLIENT_ID=c_your_client_id_here
OWNERREZ_CLIENT_SECRET=s_your_client_secret_here
OWNERREZ_REDIRECT_URI=http://localhost:3000/api/connect/ownerrez/callback

# Security
ENCRYPTION_KEY=your-random-encryption-key-here

# Server
SERVER_URL=http://localhost:3000
PORT=3000
TRANSPORT_MODE=http

2. Set Up Google OAuth Application

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable Google+ API (APIs & Services → Library)
  4. Create OAuth 2.0 credentials:
    • Go to APIs & Services → Credentials
    • Click "Create Credentials" → "OAuth 2.0 Client ID"
    • Application type: Web application
    • Authorized redirect URIs: http://localhost:3000/oauth/callback (and your production URL)
  5. Copy the Client ID and Client Secret to your .env file

3. Set Up OwnerRez OAuth Application

  1. Contact OwnerRez at partnerhelp@ownerrez.com
  2. Go to https://app.ownerrez.com/settings/api
  3. Click "Create App"
  4. Fill in:
    • Name: Your integration name
    • OAuth Redirect URL: http://localhost:3000/api/connect/ownerrez/callback
  5. Copy Client ID (starts with c_) and Client Secret (starts with s_) to .env

4. Initialize Database

The server will automatically run migrations on startup. Ensure your PostgreSQL database is accessible via the DATABASE_URL.

Running the Server

Development Mode

npm run dev:http

The server will start on http://localhost:3000.

Production Mode

npm start

Available Endpoints

OAuth & Authentication:

  • /.well-known/oauth-authorization-server - OAuth metadata for MCP clients
  • /oauth/register - Dynamic client registration
  • /oauth/authorize - OAuth authorization endpoint
  • /oauth/token - Token exchange endpoint
  • /oauth/userinfo - User information endpoint
  • /oauth/revoke - Token revocation

API Key Management:

  • POST /api/keys - Create new API key (requires OAuth)
  • GET /api/keys - List your API keys (requires OAuth)
  • DELETE /api/keys/:id - Revoke an API key (requires OAuth)

OwnerRez Integration:

  • /api/connect/ownerrez/start - Connect OwnerRez account
  • /api/connect/ownerrez/callback - OwnerRez OAuth callback
  • /api/connect/ownerrez/status - Check OwnerRez connection status

MCP Protocol:

  • /mcp - MCP protocol endpoint
  • /health - Health check

Authentication Options

This server supports two authentication methods:

  1. Google OAuth (Recommended for interactive use) - Full OAuth flow with automatic token refresh
  2. API Keys (Recommended for automation) - Simple bearer token authentication

API Key Authentication

API keys provide a simpler alternative to OAuth for MCP client connections. Here's how to use them:

Easy Method: Use the CLI Tool

The easiest way to generate an API key is using our CLI tool:

For production server:

npm run generate-api-key

For local development:

npm run generate-api-key:local

With custom options:

node generate-api-key.mjs --name "My Custom Key Name"
node generate-api-key.mjs --server https://your-server.com --name "Production Key"

The tool will:

  1. ✅ Register an OAuth client automatically
  2. ✅ Open your browser for Google authentication
  3. ✅ Exchange the authorization code for a token
  4. ✅ Create your API key
  5. ✅ Display the key and configuration example

Sample output:

🔑 OwnerRez MCP Server - API Key Generator

Server: https://ownerrez-mcp-server.fly.dev
Key Name: "CLI Generated Key"

📝 Step 1: Registering OAuth client...
✅ Client registered: mcp_a1b2c3d4...

🌐 Step 2: Starting OAuth flow...
🔐 Opening browser for Google authentication...

🔄 Step 3: Exchanging authorization code for access token...
✅ Access token obtained

🔑 Step 4: Creating API key...

================================================================================
🎉 SUCCESS! Your API key has been generated:
================================================================================

API Key: orz_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

⚠️  IMPORTANT: Save this key now - it will not be shown again!
Manual Method: Using cURL

First, you need to authenticate via Google OAuth to generate an API key:

# Get an OAuth token first (use your MCP client or direct OAuth flow)
# Then create an API key:

curl -X POST https://ownerrez-mcp-server.fly.dev/api/keys \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Desktop"}'

Response:

{
  "api_key": "orz_a1b2c3d4e5f6...",
  "key_id": "uuid",
  "key_prefix": "orz_a1b2",
  "name": "Claude Desktop",
  "created_at": "2025-10-14T...",
  "message": "API key created successfully. Save this key - it will not be shown again."
}

⚠️ Important: Save the api_key value immediately - it will never be shown again!

Step 2: Use API Key in MCP Client

Configure your MCP client with the API key as a bearer token:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ownerrez": {
      "url": "https://ownerrez-mcp-server.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer orz_a1b2c3d4e5f6..."
      }
    }
  }
}

Cursor (.cursorrules or MCP config):

{
  "mcpServers": {
    "ownerrez": {
      "url": "https://ownerrez-mcp-server.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer orz_a1b2c3d4e5f6..."
      }
    }
  }
}
Managing API Keys

List your API keys:

curl https://ownerrez-mcp-server.fly.dev/api/keys \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Revoke an API key:

curl -X DELETE https://ownerrez-mcp-server.fly.dev/api/keys/KEY_ID \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Google OAuth Authentication

For full OAuth flow with automatic token refresh:

MCP Client Configuration

Claude Desktop (OAuth)

Note: Claude Desktop needs to support OAuth-based MCP servers. Check the latest MCP SDK documentation for OAuth support.

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Local development:

{
  "mcpServers": {
    "ownerrez": {
      "url": "http://localhost:3000/mcp",
      "oauth": {
        "discovery_url": "http://localhost:3000/.well-known/oauth-authorization-server"
      }
    }
  }
}

Production server:

{
  "mcpServers": {
    "ownerrez": {
      "url": "https://ownerrez-mcp-server.fly.dev/mcp",
      "oauth": {
        "discovery_url": "https://ownerrez-mcp-server.fly.dev/.well-known/oauth-authorization-server"
      }
    }
  }
}

The MCP client will:

  1. Read the OAuth metadata from the discovery URL
  2. Automatically register itself as an OAuth client
  3. Redirect you to Google for authentication
  4. Obtain an access token
  5. Use the token for all API requests

Cursor / VSCode

Cursor and VSCode should configure similarly, using OAuth discovery:

Local development:

{
  "mcpServers": {
    "ownerrez": {
      "url": "http://localhost:3000/mcp",
      "oauth": {
        "discovery_url": "http://localhost:3000/.well-known/oauth-authorization-server"
      }
    }
  }
}

Production server:

{
  "mcpServers": {
    "ownerrez": {
      "url": "https://ownerrez-mcp-server.fly.dev/mcp",
      "oauth": {
        "discovery_url": "https://ownerrez-mcp-server.fly.dev/.well-known/oauth-authorization-server"
      }
    }
  }
}

User Flow

First-Time Setup

  1. MCP Client Registration (automatic)

    • Your MCP client automatically registers with the server
    • Receives OAuth client credentials

  2. User Authentication (via Google)

    • MCP client redirects you to Google login
    • Authenticate with your Google account
    • MCP client receives access token

  3. Connect OwnerRez (required for property management)

    • Use the MCP tool or visit /api/connect/ownerrez/start
    • Authenticate with your OwnerRez account
    • Server stores encrypted OwnerRez tokens

  4. Start Using

    • Now you can use all OwnerRez tools in your MCP client!

Subsequent Use

  • Your MCP client automatically handles token refresh
  • OwnerRez connection persists across sessions
  • No manual token management needed

Available Tools

OwnerRez Connection Management

  • check_ownerrez_connection - Check if your OwnerRez account is connected
  • connect_ownerrez - Get authorization URL to connect your OwnerRez account (required before using other tools)
  • get_oauth_url - ⚠️ DEPRECATED - Use connect_ownerrez instead

Bookings

  • list_bookings - Query bookings with filters
  • get_booking - Get single booking details
  • create_booking - Create new booking
  • update_booking - Update existing booking

Properties

  • list_properties - List all properties
  • get_property - Get single property details
  • search_properties - Search properties with availability

Guests

  • list_guests - Query guests
  • get_guest - Get guest details
  • create_guest - Create new guest
  • update_guest - Update guest
  • delete_guest - Delete guest

Quotes & Inquiries

  • list_quotes - Get all quotes
  • get_quote - Get quote details
  • list_inquiries - Get all inquiries
  • get_inquiry - Get inquiry details

Owners

  • list_owners - List all owners
  • get_owner - Get owner details

User

  • get_current_user - Get authenticated user info

Webhooks

  • list_webhook_subscriptions - List webhook subscriptions
  • get_webhook_subscription - Get webhook details
  • create_webhook_subscription - Create webhook
  • delete_webhook_subscription - Delete webhook
  • get_webhook_categories - Get available webhook categories

Reviews & Listings

  • list_reviews - Get property reviews
  • get_review - Get review details
  • list_listings - Get property listings
  • get_listing - Get listing details

Tags & Fields

  • list_tag_definitions - Get tag definitions
  • get_tag_definition - Get tag definition
  • create_tag_definition - Create tag definition
  • list_field_definitions - Get field definitions

Messages

  • list_messages - Get all messages on a thread
  • get_message - Get message details
  • create_message - Create/send a new message

Note: Messaging endpoints require messaging agreements to be signed with OwnerRez.

Usage Examples

First Time Setup

When you first connect to the MCP server, you'll need to connect your OwnerRez account:

User: "Check if I'm connected to OwnerRez"
AI: [Uses check_ownerrez_connection tool]
    "⚠️ Your OwnerRez account is not connected yet."

User: "Connect my OwnerRez account"
AI: [Uses connect_ownerrez tool]
    "🔗 Please visit this URL to connect: https://..."
    
[User clicks link, authorizes in browser]

User: "Check connection again"
AI: [Uses check_ownerrez_connection tool]
    "✅ Your OwnerRez account is connected!"

Using OwnerRez Tools

Once connected, you can interact with OwnerRez through your MCP client:

"Show me all active properties"
"List bookings for property ID 12345 from January 2025"
"Get details for booking 67890"
"Search for properties with 3+ bedrooms that allow pets"
"Show me recent inquiries"
"Create a new guest record for John Doe"

API Endpoints

OAuth Endpoints (MCP Client Authentication)

POST /oauth/register

Dynamic client registration (RFC 7591)

Request:

{
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:3000/callback"]
}

Response:

{
  "client_id": "mcp_abc123...",
  "client_secret": "mcp_secret_xyz789...",
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:3000/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "client_id_issued_at": 1234567890
}
GET /oauth/authorize

Authorization endpoint - redirects to Google for user authentication

Parameters:

  • client_id - Your registered client ID
  • redirect_uri - Your callback URI
  • response_type - Must be "code"
  • scope - Optional, defaults to "openid profile email"
  • state - Optional state parameter
POST /oauth/token

Token exchange endpoint

Request:

curl -X POST http://localhost:3000/oauth/token \
  -u "client_id:client_secret" \
  -d "grant_type=authorization_code" \
  -d "code=ac_..." \
  -d "redirect_uri=http://localhost:3000/callback"

Response:

{
  "access_token": "mcp_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "mcp_rt_...",
  "scope": "openid profile email"
}

OwnerRez Connection Endpoints

GET /api/connect/ownerrez/start

Start OwnerRez account connection (requires MCP OAuth token)

Headers:

Authorization: Bearer mcp_at_...

Response:

{
  "authorization_url": "https://app.ownerrez.com/oauth/authorize?...",
  "state": "...",
  "message": "Visit this URL to authorize OwnerRez backend access"
}
GET /api/connect/ownerrez/status

Check OwnerRez connection status

Headers:

Authorization: Bearer mcp_at_...

Response:

{
  "connected": true,
  "ownerrez_user_id": 12345,
  "connected_at": "2025-01-01T00:00:00Z"
}

Deployment

Local Development

npm run dev:http

Production (Fly.io)

  1. Install Fly CLI: https://fly.io/docs/hands-on/install-flyctl/
  2. Login: flyctl auth login
  3. Create app: flyctl launch
  4. Set secrets: 
    flyctl secrets set DATABASE_URL=postgresql://...
flyctl secrets set GOOGLE_CLIENT_ID=xxx
flyctl secrets set GOOGLE_CLIENT_SECRET=xxx
flyctl secrets set GOOGLE_REDIRECT_URI=https://your-app.fly.dev/oauth/callback
flyctl secrets set OWNERREZ_CLIENT_ID=c_xxx
flyctl secrets set OWNERREZ_CLIENT_SECRET=s_xxx
flyctl secrets set OWNERREZ_REDIRECT_URI=https://your-app.fly.dev/api/connect/ownerrez/callback
flyctl secrets set ENCRYPTION_KEY=xxx
flyctl secrets set SERVER_URL=https://your-app.fly.dev
  5. Deploy: flyctl deploy

Using ngrok for Local Testing

# Install ngrok: https://ngrok.com/download
ngrok http 3000

# Update your .env with the ngrok URL:
# GOOGLE_REDIRECT_URI=https://abc123.ngrok.io/oauth/callback
# OWNERREZ_REDIRECT_URI=https://abc123.ngrok.io/api/connect/ownerrez/callback
# SERVER_URL=https://abc123.ngrok.io

Troubleshooting

OAuth Authentication Issues

"Invalid client_id"

  • Ensure your MCP client has registered via /oauth/register
  • Check that client credentials are being sent correctly

"Invalid redirect_uri"

  • The redirect URI must match exactly what was registered
  • Include protocol (http:// or https://)

"Invalid or expired access token"

  • Access tokens expire after 1 hour
  • Your MCP client should automatically refresh using the refresh token

Google OAuth Issues

"redirect_uri_mismatch"

  • Ensure the redirect URI in your .env matches what's configured in Google Cloud Console
  • Check for trailing slashes

"access_denied"

  • User denied access during Google OAuth
  • User needs to authorize the application

OwnerRez Connection Issues

"No OwnerRez connection found for user"

  • You must connect your OwnerRez account first
  • Visit /api/connect/ownerrez/start or use the get_oauth_url tool

"403 Forbidden" from OwnerRez API

  • Check that your OwnerRez OAuth app is properly configured
  • Verify your IP isn't blocked by OwnerRez
  • Contact OwnerRez support

Database Issues

"DATABASE_URL environment variable is not set"

  • Ensure .env file exists and contains DATABASE_URL
  • Check PostgreSQL is running and accessible

Migration errors

  • Ensure PostgreSQL user has necessary permissions
  • Check database exists and is accessible

Security Notes

  • Never commit your .env file or expose secrets
  • Store OAuth client secrets securely
  • Use HTTPS for production redirect URIs
  • Regularly rotate your encryption key if compromised
  • Access tokens are short-lived (1 hour) and automatically refreshed
  • OwnerRez tokens are encrypted at rest using AES-256-GCM

Premium Features

Some endpoints require premium OwnerRez features:

  • Messaging: Requires messaging partnership agreement
  • Listings: Requires WordPress Plugin + Integrated Websites feature

Contact OwnerRez at partnerhelp@ownerrez.com for access.

Development

# Watch mode for development
npm run watch

# Build
npm run build

# Run
npm start

# Run in HTTP mode for testing
npm run dev:http

Resources

License

Apache-2.0

Support

For issues with: