Servidor MCP de OwnerRez

Un servidor de Protocolo de Contexto de Modelo que conecta OwnerRez con Claude (Cowork / Claude Desktop) y cualquier otro cliente MCP. Pregunta sobre reservas, mira quién está registrado, envía mensajes a los huéspedes, registra gastos y gestiona webhooks — en lenguaje natural. Construido con Python + FastMCP.

⚠️ Proyecto comunitario, no afiliado a OwnerRez.

Inicio rápido

¿Nuevo aquí? QUICKSTART.md te lleva a una conexión funcional en dos comandos.

La ruta más rápida — sin clonar, sin venv — usando uv:

Este mismo servidor funciona en cualquier cliente MCP — Claude, Cursor, Windsurf, VS Code, Cline, Zed y más. Añade el bloque estándar de abajo a la configuración MCP de tu cliente (QUICKSTART.md lista la ubicación del archivo de configuración de cada cliente y los pocos que usan una clave diferente):

{
  "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"
      }
    }
  }
}

Reinicia tu cliente y las herramientas de OwnerRez aparecen. Eso es todo.

¿Prefieres ejecutar desde el código fuente? Consulta Instalar desde el código fuente.

Qué puede hacer

Herramientas

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

Verificado contra la API en vivo — dos limitaciones de OwnerRez a tener en cuenta: no hay un endpoint público para crear gastos, y no hay un endpoint que liste hilos de mensajes. Los mensajes entrantes de huéspedes llegan a través de webhooks — suscríbete a la categoría message con create_webhook_subscription, luego usa el threadId del evento con list_messages / send_message. Las reservas y los huéspedes están limitados por un tiempo "desde", no por fechas de estancia.

Ejemplos de prompts

• "¿Quién se registra este fin de semana?"

• "¿Quién se está quedando actualmente en la Casa de la Playa?"

• "Redacta un mensaje de check-in para el huésped que llega mañana a la Cabaña 3."

• "Muéstrame todos los pagos de la reserva 84213."

• "Lista los mensajes del hilo 55123 y redacta una respuesta."

Autenticación

Elige la que mejor se adapte — el servidor prefiere OAuth si ambos están configurados.

Token de Acceso Personal (lo más simple para una cuenta). OwnerRez → Configuración → API → Tokens de Acceso Personal. Establece OWNERREZ_USERNAME + OWNERREZ_TOKEN.

OAuth (para múltiples cuentas / distribución). Crea una aplicación OAuth en OwnerRez, establece OWNERREZ_CLIENT_ID + OWNERREZ_CLIENT_SECRET, luego ejecuta el asistente integrado:

ownerrez-mcp auth

Abre la página de autorización, captura el redirect localmente e imprime el OWNERREZ_ACCESS_TOKEN para guardarlo.

Mensajes entrantes reales (receptor de webhooks)

OwnerRez no tiene un endpoint para consultar conversaciones abiertas — los mensajes entrantes de huéspedes se entregan a través de webhooks. Este paquete incluye un pequeño receptor que los captura en un almacén local para que list_open_messages se convierta en una bandeja de entrada real.

# 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

Luego registra esa URL (a través de la herramienta MCP o cualquier cliente):

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

Ahora los mensajes entrantes de huéspedes llegan al almacén, y en tu agente puedes preguntar "muéstrame mis mensajes abiertos" (list_open_messages), responder con send_message usando el thread_id del mensaje, y mark_message_handled para limpiarlo.

Configuración: OWNERREZ_STORE (ruta de la base de datos, por defecto ~/.ownerrez-mcp/messages.db), OWNERREZ_WEBHOOK_HOST / OWNERREZ_WEBHOOK_PORT, y un opcional OWNERREZ_WEBHOOK_SECRET (enviado como X-Webhook-Secret o ?secret=) para rechazar publicaciones no autenticadas. Ejecuta siempre detrás de HTTPS.

Seguridad: modo de solo lectura

Establece OWNERREZ_READ_ONLY=1 para bloquear firmemente cada herramienta de escritura (mensajería, gastos, cambios de webhook). Ideal para permitir que un asistente explore tus datos sin ningún riesgo de que envíe mensajes a un huésped o modifique registros.

Verificar contra la API en vivo

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

La salida te dice exactamente qué endpoints puede alcanzar tu token y si la creación de gastos es WRITABLE o NOT SUPPORTED.

Instalar desde el código fuente

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

Apunta tu cliente MCP al ejecutable del venv:

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

Referencia de configuración

Desarrollo

ruff check .   # lint
pytest         # tests

Consulta CONTRIBUTING.md. Cada herramienta devuelve un sobre estructurado {"ok": ...}, sigue la paginación v2 de OwnerRez, redacta secretos de errores y reintenta fallos transitorios.

Licencia

MIT — consulta LICENSE. Referencia de la API: https://api.ownerrez.com/help/v2