@rentalot/mcp-server

MCP server for the Rentalot API. Manage rental properties, contacts, showings, conversations, and more from any AI assistant.

Setup

Claude Code

claude mcp add rentalot -e RENTALOT_API_KEY=ra_your_key -- npx -y @rentalot/mcp-server

Codex (OpenAI)

codex mcp add --env RENTALOT_API_KEY=ra_your_key -- npx -y @rentalot/mcp-server

Gemini CLI

gemini mcp add --transport stdio rentalot -- npx -y @rentalot/mcp-server

Then add the env var to ~/.gemini/settings.json:

{
  "mcpServers": {
    "rentalot": {
      "command": "npx",
      "args": ["-y", "@rentalot/mcp-server"],
      "env": { "RENTALOT_API_KEY": "ra_your_key" }
    }
  }
}

Claude Desktop / Cursor / Windsurf

All three use the same JSON format — just different file paths:

| Client | Config file | |--------|-------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) | | Windsurf | ~/.codeium/windsurf/mcp_config.json |

{
  "mcpServers": {
    "rentalot": {
      "command": "npx",
      "args": ["-y", "@rentalot/mcp-server"],
      "env": {
        "RENTALOT_API_KEY": "ra_your_key"
      }
    }
  }
}

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rentalot": {
      "type": "local",
      "command": ["npx", "-y", "@rentalot/mcp-server"],
      "environment": { "RENTALOT_API_KEY": "ra_your_key" },
      "enabled": true
    }
  }
}

Get Your API Key

1. Go to Rentalot API Keys
2. Click Create API Key
3. Copy the key (starts with ra_)

Local development and trial testing

The MCP client defaults to https://rentalot.ai. For a local Rentalot development server, set the API origin explicitly:

export RENTALOT_BASE_URL=http://localhost:3000
export RENTALOT_API_KEY=ra_your_development_key

The development-only trial requires an existing account and an API key owned by that account. It permits private, account-owned property and contact CRUD only. Production trial access is disabled, and Starter remains read-only. Do not point a trial walkthrough at production.

Trial limits are shared across all keys and clients for the account. Key rotation does not restart the trial or restore lifetime quota. A key issued during the trial keeps its original expiry after a paid upgrade, so create a new paid key for continued paid access.

Authentication

You can provide your API key in two ways. Environment variables take priority over the config file.

Option A: Config file (recommended)

Save your key once and every MCP client picks it up automatically — no need to set RENTALOT_API_KEY in each client's config:

mkdir -p ~/.config/rentalot
cat > ~/.config/rentalot/config.yaml << 'EOF'
api_key: ra_your_key
EOF
chmod 600 ~/.config/rentalot/config.yaml

Then register the server without any env var:

# Claude Code
claude mcp add rentalot -- npx -y @rentalot/mcp-server

# Codex
codex mcp add -- npx -y @rentalot/mcp-server

Option B: Environment variable

Pass RENTALOT_API_KEY in your MCP client config (shown in the setup examples above). This overrides the config file.

Config file reference (~/.config/rentalot/config.yaml):

# Required
api_key: ra_your_key

# Optional — defaults to https://rentalot.ai
# base_url: http://localhost:3000

Respects $XDG_CONFIG_HOME — if set, looks for $XDG_CONFIG_HOME/rentalot/config.yaml instead.

Resolution order: RENTALOT_API_KEY env var > api_key in config file. RENTALOT_BASE_URL similarly overrides base_url; the default origin is https://rentalot.ai.

Quota recovery

When a tool returns a rate-limit error, wait for the reported Retry-After duration. If it is absent, use X-RateLimit-Reset. Daily development-trial budgets reset at UTC midnight. Lifetime trial request/write budgets are account-owned and do not reset when rotating keys or switching MCP clients.

AI Agent Skill

This project ships a SKILL.md following the Agent Skills open standard. Install it so your coding agent knows all 65 tools, common workflows, and API patterns.

Quick install with skills CLI (by Vercel Labs):

npx skills add ariel-frischer/rentalot-mcp

Claude Code — Skills live in ~/.claude/skills/ (global) or .claude/skills/ (project-local).

# Global — available in all projects
mkdir -p ~/.claude/skills/rentalot-mcp
curl -fsSL https://raw.githubusercontent.com/ariel-frischer/rentalot-mcp/main/.skills/default/SKILL.md \
  -o ~/.claude/skills/rentalot-mcp/SKILL.md

# Project-local — checked into this repo only
mkdir -p .claude/skills/rentalot-mcp
curl -fsSL https://raw.githubusercontent.com/ariel-frischer/rentalot-mcp/main/.skills/default/SKILL.md \
  -o .claude/skills/rentalot-mcp/SKILL.md

Codex CLI — reads skills from ~/.codex/skills/ (global) or .codex/skills/ (project-local).

# Global
mkdir -p ~/.codex/skills/rentalot-mcp
curl -fsSL https://raw.githubusercontent.com/ariel-frischer/rentalot-mcp/main/.skills/default/SKILL.md \
  -o ~/.codex/skills/rentalot-mcp/SKILL.md

# Project-local
mkdir -p .codex/skills/rentalot-mcp
curl -fsSL https://raw.githubusercontent.com/ariel-frischer/rentalot-mcp/main/.skills/default/SKILL.md \
  -o .codex/skills/rentalot-mcp/SKILL.md

Or pass directly: codex --instructions .skills/default/SKILL.md

Detailed API Skill

For deeper API reference (full field lists, status enums, webhook events), there's also a comprehensive skill at skills/rentalot/SKILL.md. Symlink it for Claude Code:

ln -s "$(pwd)/skills/rentalot" ~/.claude/skills/rentalot

Then invoke with /rentalot in any Claude Code session.

Tools (65)

| Resource | Tools | Access | |----------|-------|--------| | Properties (5) | list_properties, get_property, create_property, update_property, delete_property | Read: Starter+ / Write: Pro+ | | Contacts (5) | list_contacts, get_contact, create_contact, update_contact, delete_contact | Read: Starter+ / Write: Pro+ | | Showings (6) | list_showings, get_showing, create_showing, update_showing, delete_showing, check_showing_availability | Read: Starter+ / Write: Pro+ | | Events (1) | list_events | Read: Starter+ | | Conversations (4) | list_conversations, get_conversation, search_conversations, list_conversation_messages | Read: Starter+ | | Messages (1) | send_message | Write: Pro+ | | Drafts (6) | list_drafts, get_draft, create_draft, update_draft, send_draft, delete_draft | Read: Starter+ / Write: Pro+ | | Follow-ups (4) | list_followups, get_followup, create_followup, delete_followup | Read: Starter+ / Write: Pro+ | | Workflows (8) | list_workflows, get_workflow, create_workflow, update_workflow, delete_workflow, trigger_workflow_run, list_workflow_runs, get_workflow_run | Read: Starter+ / Write: Pro+ | | Webhooks (7) | list_webhooks, create_webhook, get_webhook, update_webhook, delete_webhook, test_webhook, rotate_webhook_secret | Pro+ | | Settings (4) | get_settings, update_settings, get_followup_settings, update_followup_settings | Read: Starter+ / Write: Pro+ | | Property Images (9) | list_property_images, presign_image_upload, confirm_image_upload, delete_property_images, reorder_property_images, presign_image_batch, confirm_image_batch, import_property_images, get_image_import_job | Read: Starter+ / Write: Pro+ | | Sessions (3) | list_sessions, get_session, review_session | Read: Starter+ / Write: Pro+ | | Bulk Import (2) | bulk_create_properties, get_bulk_import_job | Pro+ |

Property contract

Property creation and updates accept an optional canonical propertyType: house, apartment, condo, townhouse, or room. Existing callers may omit it, and legacy reads may return null. Studio is represented by bedrooms=0; use the exact bedroomType=studio filter, and repeat propertyType query values to match any selected type.

create_property and update_property also accept optional unitNumber (string or null, maximum 50 characters). Pass null or a blank string to clear it; when omitted, the API parses a trailing Unit, Apt, Suite, or # suffix from the address. Property objects returned by list/get/create/update include unitNumber: string | null and read-only buildingId: string | null, the account-scoped building UUID grouping apartment/condo units. Do not send buildingId in property writes. Bulk imports accept flexible property records and pass their fields through without an explicit field map.

Resources

• docs://api-reference — Full API reference (authentication, rate limits, pagination, errors, all resource schemas)

Development

bun install
bun run build      # Compile TypeScript
bun run dev        # Run with --watch (hot reload)
bun run lint       # ESLint
bun run typecheck  # tsc --noEmit
bun run test:e2e   # E2E test all 65 tools against local dev server

License

MIT