cloudbeds-mcp-server

Servidor MCP que expõe ocupação, check-ins/check-outs e reservas do Cloudbeds como tools de linguagem natural, sem nenhum caminho de escrita na v1 — por decisão de design, não por limitação técnica.

A coisa em ação

Sem UI — é um servidor MCP (stdio). A imagem abaixo é a suíte de testes rodando de verdade; o restante das capturas reais (setup rejeitando uma key inválida contra a API ao vivo do Cloudbeds, tools nos dois estados do servidor) está na seção Prints.

Related MCP server: libredesk-mcp

Links

Repositório:  https://github.com/ronaldoribeirosm/cloudbeds-mcp-server
Demo:         sem demo pública — cada instalação precisa da API key e do
              Property ID do Cloudbeds de um hotel real; não dá pra expor
              isso num ambiente compartilhado sem vazar dado de hóspede
Docs/Swagger: não se aplica — não é uma API HTTP. A superfície de tools
              (nomes, parâmetros, descrições) está documentada na tabela
              abaixo e é a mesma coisa que o cliente MCP lista via
              `list_tools()`
Vídeo:        [ opcional — não gravado ]

O problema

Consultar ocupação, check-ins do dia ou o status de uma reserva no Cloudbeds hoje significa abrir o painel, navegar até a tela certa e ler manualmente — ou interromper quem está na recepção pra perguntar. Isso já tinha sido resolvido uma vez no automacao-recepcao, só que atrás de uma UI Streamlit: resolve pra quem abre aquela tela, não pra quem só quer perguntar "quantos check-ins tenho hoje?" de dentro do assistente de IA que já está usando.

A solução ingênua seria integrar a API do Cloudbeds direto em cada assistente de IA que alguém usa — um conector pro Cursor, outro pra qualquer coisa que apareça depois. Isso não escala: N ferramentas de IA × M integrações de dado vira N×M código de cola. MCP inverte essa conta — escreve-se um servidor, e qualquer cliente compatível com o protocolo consegue chamá-lo.

sequenceDiagram
    participant Agente as Agente de IA
    participant MCP as cloudbeds-mcp-server
    participant CB as API Cloudbeds

    Agente->>MCP: "quantos check-ins tenho hoje?"
    MCP->>CB: GET getReservations (checkInFrom=checkInTo=hoje)
    CB-->>MCP: lista de reservas
    MCP-->>Agente: texto formatado, pronto pra responder

A solução (visão geral)

• Camada de tools (src/cloudbeds_mcp/tools/) separa lógica pura (compute_*, format_*, sem I/O) da tool MCP em si (register_*_tools) — a mesma separação que o automacao-recepcao já fazia entre regra de negócio e interface Streamlit, só que aqui o "front-end" é o protocolo MCP.

• Camada de auth (src/cloudbeds_mcp/auth.py) valida a API key com uma chamada real ao Cloudbeds antes de gravar qualquer coisa, criptografa em disco, e nunca devolve a key pro modelo de IA depois de configurada.

• Cliente HTTP (src/cloudbeds_mcp/cloudbeds_client.py) reaproveita a lógica de retry/paginação e as descobertas de comportamento real da API já validadas no projeto irmão — sem herdar nenhum dos métodos de escrita.

• Detalhes completos na seção Decisões técnicas abaixo.

Prints — o projeto rodando

Sem uma conta Cloudbeds real disponível, três coisas foram validadas de verdade, capturadas em screenshot (não é texto inventado — é a saída real dos comandos):

1. Suíte de testes e lint:

2. --setup com uma API key inválida — bateu na API real do Cloudbeds e voltou um 401 de verdade:

Isso confirma que o endpoint de validação (getHotels) existe e se comporta como assumido — o que faltava validar era só o caminho de sucesso (key válida), que segue sem teste ao vivo.

3. As tools nos dois estados do servidor (antes e depois do setup), capturado chamando list_tools() de verdade, mais a saída real de format_occupancy_snapshot()/format_movements() contra os dados de tests/test_occupancy.py:

Stack

Como rodar localmente

git clone https://github.com/ronaldoribeirosm/cloudbeds-mcp-server
cd cloudbeds-mcp-server
pip install -e ".[dev]"
cloudbeds-mcp-server --setup

O --setup pede a API key e o Property ID do Cloudbeds (Configurações > API no painel), valida com uma chamada real e salva criptografado em ~/.cloudbeds-mcp/credentials.enc. Depois disso, aponte um cliente MCP pro binário cloudbeds-mcp-server (exemplo de config em mcp_client_config.example.json).

Rodar os testes:

pytest -v
ruff check .

Decisões técnicas

Por que nenhuma tool de escrita existe na v1

O dilema: dava pra implementar putGuest/postReservationNote reaproveitando o cliente do automacao-recepcao — a API já suporta. A escolha foi não implementar nenhum método de escrita no cliente desta v1 — não é uma flag de segurança que dá pra contornar, é a própria classe CloudbedsClient deste projeto que não tem o método. Um agente de IA com acesso só-leitura pode, na pior das hipóteses, vazar um dado que já tinha permissão de ver; nunca alterar uma reserva ou um preço sozinho sem confirmação humana. Escrita fica pra v2, atrás de um design de confirmação explícita que ainda não existe.

Por que a API key nunca "aparece" de volta

O dilema: o jeito mais simples de guardar uma credencial de API é variável de ambiente ou arquivo de texto plano — mas isso é publicável, e qualquer pessoa que rode este servidor está potencialmente compartilhando a key com o histórico de conversa de um agente de IA. A escolha: configure_cloudbeds_api_key recebe a key só pra validar (uma chamada real de getHotels) e gravar; a função devolve só o nome do hotel conectado, nunca a key — nem em sucesso, nem no texto de erro de falha. O arquivo fica criptografado com Fernet fora da pasta do projeto (~/.cloudbeds-mcp/), com permissão restrita ao dono. Isso está coberto por teste: test_credentials_file_is_encrypted_on_disk falha se o valor da key aparecer em texto puro no arquivo salvo em disco.

Por que a busca por nome varre reservas em vez de filtrar no servidor

Descoberta herdada do automacao-recepcao (confirmada contra a API real do Cloudbeds em 2026-07-22, não retestada aqui por falta de credencial): getReservations ignora filtro por nome, e getGuestList só filtra de verdade no servidor por e-mail ou telefone exato — nunca por nome parcial. A alternativa seria buscar todas as páginas de reservas da propriedade inteira, o que não escala pra contas com anos de histórico. A solução adotada limita a varredura a uma janela de 12 meses passados + 3 meses futuros e filtra por substring em memória — resolve o caso de uso real ("achar o hóspede que acabou de ligar") sem paginar a conta inteira, ao custo de não achar hóspedes fora dessa janela (documentado como limitação conhecida, não escondido).

Por que get_occupancy_today detalha reserva por reserva

getReservations (lista) não traz quarto nem datas por quarto — só getReservation (individual) traz o array assigned, que é o que permite saber se um quarto específico está ocupado hoje. Isso também foi uma descoberta real do projeto irmão, não uma suposição de documentação. Por isso a tool primeiro filtra candidatos "baratos" pela lista (reservas não canceladas cujo check-out é depois de hoje) e só depois detalha cada uma — evita bater getReservation pra cada reserva histórica da propriedade.

Testes — o que é coberto e por quê

Resultado real: 31/31 testes passando. ruff check . limpo.

O que eu faria diferente

• Só o caminho de erro foi testado contra a API real — não tenho uma key válida disponível agora. Rodar --setup com uma key inválida confirmou que getHotels é um endpoint real e rejeita corretamente (401), mas o formato exato da resposta de sucesso (o propertyName que validate_and_save espera encontrar em hotels[0]) segue assumido a partir do guia original, não confirmado ao vivo. Primeira coisa a fazer antes de publicar: rodar --setup contra um hotel de teste de verdade e corrigir o que a API real devolver diferente do assumido.

• get_guest_by_name escala mal em contas com muito histórico — varrer 15 meses de reservas por substring funciona pra um hotel pequeno/médio, mas numa conta com dezenas de milhares de reservas isso fica lento. Combinar com getGuestList quando o usuário já tiver e-mail ou telefone (mais rápido, filtro real no servidor) resolveria a maioria dos casos.

• Sem cache — cada chamada de tool bate a API do zero, mesmo pra dados que não mudam a cada segundo (lista de quartos, por exemplo). Um cache curto (TTL de alguns minutos) em get_rooms reduziria bastante chamada repetida.

• v2 do guia original não entrou nesta v1 — get_occupancy_forecast, get_guest_stay_history, search_available_rooms e o resource daily_report ficaram de fora por escopo, não por dificuldade técnica; a base de cliente/auth já suporta.

Licença

MIT.