Conectar Cloudbeds a Claude

Por qué Cloudbeds primero

Cloudbeds publica una OpenAPI spec completa en developers.cloudbeds.com y mantiene un SDK Python oficial generado automáticamente vía OpenAPI Generator. Eso significa que el conector InnovaSuite no improvisa endpoints — los consume desde el contrato pinned en el SDK. Tres consecuencias prácticas:

1. Setup en 20 minutos, no en 2 días.
2. Idempotencia garantizada por contrato — los IDs de Cloudbeds son estables y los eventos llegan con version y etag.
3. OAuth 2.0 estándar — sin tokens custom, sin headers raros.

Pre-requisitos

• Cuenta Cloudbeds (sandbox o producción).
• App registrada en developers.cloudbeds.com con client_id y client_secret.
• Claude Desktop (Mac/Windows/Linux) o Claude Code instalado.
• Python 3.12 o superior.

Paso 1 — Clona el repo del Connector Hub

git clone https://github.com/innovasuite/innovasuite-pms-connector-hub.git
cd innovasuite-pms-connector-hub
pip install -e .

Esto instala el hub y todos sus connectors, incluido cloudbeds.

Paso 2 — Configura las credenciales Cloudbeds

Crea el archivo ~/.secrets/pms/demo/cloudbeds.env:

CLOUDBEDS_CLIENT_ID=tu_client_id_aqui
CLOUDBEDS_CLIENT_SECRET=tu_client_secret_aqui
CLOUDBEDS_PROPERTY_ID=tu_property_id_aqui
DATABASE_URL=sqlite:///./hub.db
MCP_TENANT_ID=demo

Nota de seguridad: el directorio ~/.secrets/ está en el .gitignore y nunca debe entrar en un repo público. El conector lo lee al arrancar y nunca persiste credenciales en la base de datos.

Paso 3 — Inicializa la base de datos local

python -m innovasuite_hub.db init

Esto crea hub.db (SQLite) con el schema canónico. La primera ingesta se ejecuta automáticamente al arrancar el MCP server.

Paso 4 — Añade el server MCP a Claude

Para Claude Desktop, edita ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "innovasuite-pms": {
      "command": "python",
      "args": ["-m", "innovasuite_hub.mcp_servers.pms_unified"],
      "env": {
        "MCP_TENANT_ID": "demo"
      }
    }
  }
}

Para Claude Code, edita ~/.claude/.mcp.json con el mismo bloque.

Reinicia Claude Desktop o tu sesión de Claude Code.

Paso 5 — Pruébalo

Abre Claude y prueba:

"Lista las próximas 10 reservas en Cloudbeds para mi hotel demo."

"¿Cuál fue la ocupación media en abril? Compárala con marzo."

"Muéstrame las tarifas activas para la habitación Standard este fin de semana."

Las tres son operaciones Tier 1 (lectura) — siempre permitidas.

Paso 6 — Prueba el guard de seguridad (Tier 3)

Pide a Claude algo destructivo:

"Cancela la reserva ABC123."

Debes ver:

[PMS-DENY-T3] cancel_reservation requires signed admin operation,
not available via MCP. Reason: Tier 3 hard-deny.

El guard funciona. Tu hotel no puede ser cancelado por accidente vía conversación.

Tools MCP expuestos para Cloudbeds

Tool	Tier	Descripción
pms__list_reservations(pms="cloudbeds", property_id, since)	1	Lista reservas desde una fecha.
pms__get_reservation(pms="cloudbeds", source_id)	1	Detalle de una reserva.
pms__list_rooms(pms="cloudbeds", property_id)	1	Inventario de habitaciones.
pms__list_rate_plans(pms="cloudbeds", property_id, date_range)	1	Tarifas activas.
pms__compute_occupancy(property_id, date_range)	1	Ocupación canónica (cross-PMS).
pms__compare_adr(property_ids, period)	1	Comparativa ADR (cross-PMS).
pms__create_reservation(...)	2	Solo con confirmación humana.
pms__cancel_reservation(...)	3	Bloqueado vía MCP. Solo CLI firmada.

Troubleshooting

Error 401 invalid_client — verifica que client_id/client_secret están bien en cloudbeds.env. No incluyas comillas alrededor del valor.

Error 404 property not found — confirma CLOUDBEDS_PROPERTY_ID. En la pestaña "Settings → Properties" del dashboard Cloudbeds.

Claude no ve los tools — revisa que el bloque MCP está en el archivo correcto y que Claude se ha reiniciado. Para Claude Code: claude mcp list debería mostrar innovasuite-pms.

Las reservas no se actualizan — el conector hace poll cada 60s en el sprint actual. Webhook llegará en sprint 2.

Próximos pasos

Si esto te ha funcionado, deberías:

1. Compartir feedback con nosotros — somos pequeños y oímos a nuestros usuarios cero.
2. Considerar el plan Connector Hub Pro (gestionado, sin instalar nada en local, dashboard incluido).
3. Pedir el conector para tu otro PMS si tienes propiedades multi-stack.