Come collegare apaleo a Gemini via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → apaleo, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

apaleo + Gemini

Gestione alberghiera nel PMS cloud apaleo: strutture, camere e tipologie di camera, piani tariffari e tariffe, disponibilità e offerte, prenotazioni, reservation e ospiti, gruppi, folio, pagamenti, fatture, manutenzione, housekeeping e report di performance. Crea prenotazioni, assegna camere ed esegue check-in e check-out. Si collega come app con OAuth2 client credentials; cancellazioni e no-show sono disattivati all'installazione.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

APALEO_CLIENT_ID, APALEO_CLIENT_SECRET

Step 1 — Ottieni le credenziali

La configurazione richiede circa 5 minuti. Ti serve un account apaleo con accesso ad Apps. Non c'è un accesso dal browser: il connettore si autentica come app con il grant OAuth2 client credentials.

1. In apaleo apri Apps > Connected apps > Add a custom app (oppure su apaleo.dev registra un OAuth simple client con client credentials).
2. Dai all'app i permessi che servono al team. Per la lettura, per esempio properties.read, unitgroups.read, units.read, rateplans.read, rates.read, services.read, companies.read, availability.read, offers.read, reservations.read, groups.read, blocks.read, folios.read, payments.read, invoices.read, maintenances.read e reports.read; per le scritture reservations.create, reservations.manage, reservations.assign-unit, maintenances.create e operations.change-room-state. Ometti i permessi di scrittura per un connettore in sola lettura.
3. Copia il client id in APALEO_CLIENT_ID e il client secret in APALEO_CLIENT_SECRET. Il secret viene mostrato una sola volta; se lo perdi, creane uno nuovo nell'app.
4. Installa il connettore ed esegui apaleo_list_properties per verificare la connessione.

Il connettore ottiene un token da https://identity.apaleo.com/connect/token e lo rinnova ogni ora. Ogni chiamata gira come custom app con i suoi permessi; un permesso mancante all'app risponde 403.

Cosa legge:

• Inventario e tariffe: strutture (hotel), unit group (tipologie di camera), unit (camere) con stato di pulizia e manutenzione, piani tariffari, prezzi per notte con restrizioni (apaleo_list_rates), servizi (extra come colazione o parcheggio), politiche di cancellazione e aziende (clienti corporate).
• Disponibilità e offerte: camere rimaste per tipologia e notte (apaleo_get_unit_group_availability), camere libere per tutto un soggiorno (apaleo_get_unit_availability), camere assegnabili a una reservation, e apaleo_get_offers, i piani tariffari prenotabili con i prezzi per un soggiorno.
• Prenotazioni e reservation: apaleo_list_reservations con text_search (nome, email, id della reservation) e date_filter Arrival, Departure o Stay insieme a from e to; apaleo_count_reservations conta senza caricarle. Inoltre prenotazioni, servizi di una reservation, gruppi e blocchi. Gli ospiti fanno parte delle reservation (primaryGuest, additionalGuests) e delle prenotazioni (booker).
• Contabilità: folio (conti degli ospiti, da trovare con reservation_ids), pagamenti sui folio e fatture.
• Operatività e report: finestre di manutenzione, performance della struttura (occupazione, ADR, RevPAR), ricavi per conto con netto, lordo e IVA (per al massimo un anno) e arrivi al giorno in un mese.

Cosa scrive:

• Prenotazioni: apaleo_create_booking con il ratePlanId e un timeSlice per notte presi da apaleo_get_offers. apaleo_update_booking e apaleo_update_reservation accettano operazioni JSON Patch come [{"op": "replace", "path": "/comment", "value": "Late arrival"}]. apaleo_amend_reservation cambia arrivo, partenza, numero di ospiti, piano tariffario e prezzo per notte.
• Reception: apaleo_assign_unit (apaleo sceglie una camera libera) oppure apaleo_assign_specific_unit, apaleo_unassign_units, apaleo_check_in_reservation (annullabile con apaleo_revert_check_in) e apaleo_check_out_reservation, che addebita sul folio tutte le voci aperte e funziona solo se la partenza non è oltre domani.
• Housekeeping e manutenzione: apaleo_set_unit_conditions (Clean, CleanToBeInspected, Dirty) e apaleo_create_maintenance (OutOfService, OutOfOrder, OutOfInventory).

Prenotazioni, check-in e check-out cambiano l'hotel in tempo reale, quindi l'AI ti mostra cosa sta per modificare e aspetta il tuo sì.

Disattivati all'installazione: apaleo_cancel_reservation (si applica la penale della politica del piano tariffario e una reservation cancellata non si può riattivare) e apaleo_set_reservation_no_show (addebita la penale di no-show sul folio e non si può annullare). Un admin li attiva quando servono al team.

Formati dei dati: gli id sono codici leggibili: una struttura MUC, una unit group MUC-DBL, una unit MUC-101, un piano tariffario MUC-FLEX-DBL, una prenotazione ABCDEF, le sue reservation ABCDEF-1 e ABCDEF-2, un folio ABCDEF-1-1. Gli importi sono {"amount": 120.0, "currency": "EUR"} in unità intere; il balance di una reservation è negativo quando l'ospite deve ancora pagare. Le date sono YYYY-MM-DD; gli orari sono ISO 8601 con l'offset UTC della struttura. Una notte appartiene al giorno operativo in cui inizia; to è incluso per disponibilità e performance, escluso per il report dei ricavi. Lo stato di una reservation è Confirmed, InHouse, CheckedOut, Canceled o NoShow. I filtri con più valori sono separati da virgole senza spazi (status: Confirmed,InHouse) e expand aggiunge oggetti incorporati (expand: booker,assignedUnits).

Paginazione: le liste accettano page_number (da 1) e page_size (fino a 500) e restituiscono il totale in count. Una pagina oltre la fine risponde 204 No Content: non c'è altro.

Errori comuni: 401 indica client id o secret errati o un token scaduto. 403 indica un permesso mancante sulla custom app. 404 è un id sconosciuto. 422 è una regola di business, per esempio un check-in prima del giorno di arrivo, nessuna camera assegnata o un'offerta esaurita, con il motivo in messages. 429 è il limite di richieste.

Il connettore non registra addebiti o pagamenti, non crea fatture, non modifica piani tariffari, prezzi o inventario e non gestisce utenti o app di apaleo.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Gemini

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di apaleo.

Tool disponibili

Esempi di prompt

• "Quali reservation arrivano oggi a MUC e quali non hanno ancora una camera assegnata?"
• "Quante doppie sono ancora libere venerdì e sabato prossimi, e quanto costa la tariffa flessibile per le due notti?"
• "Mostrami occupazione, ADR e RevPAR del mese scorso rispetto al mese precedente."
• "Assegna una camera pulita alla reservation ABCDEF-1 e fai il check-in dell'ospite."
• "Segna le camere da MUC-101 a MUC-105 come pulite e metti MUC-210 fuori servizio fino a lunedì per una doccia rotta."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Cursor
• Collegare a Meta Muse
• Collegare a Microsoft Copilot