smoobu-mcp
# smoobu-mcp
Read-only [MCP](https://modelcontextprotocol.io) server over the Smoobu API, built for the monthly
close and invoicing of a small portfolio of vacation rentals in Costa Rica. It replaces hand-pulled
BookingList exports with six tools that return normalized, flagged, auditable rows.
| Tool | Purpose |
|---|---|
| `list_properties` | 14 properties with Smoobu id, EOM entity and fiscal company / bsides account |
| `get_bookings` | Arrival-based, inclusive on both ends, fully paged, with header totals, flags and an optional EOM-ready layout |
| `get_booking` | One booking with price elements, created/modified timestamps and the raw object |
| `changes_since` | New / modified (old → new) / cancelled since a previous extraction |
| `stays_in_month` | Pro-rata by night inside the month, to reconcile with Smoobu Analytics |
| `smoobu_health` | Auth and account check, never returns keys |
Status: **scaffolded, not yet verified against the live API.** See `tasks/BOARD.md`.
## Run locally (stdio)
```bash
cp .env.example .env # add SMOOBU_API_KEY and SMOOBU_API_SECRET (Smoobu: Settings > Advanced > API Keys)
npm install && npm run build
```
Claude Code: `claude mcp add smoobu -- node /path/to/smoobuMCP/dist/index.js` (reads `.env` from the
working directory; or pass the variables with `-e`). Claude Desktop: add the same command to
`claude_desktop_config.json`.
## Develop
`npm run check` runs typecheck, lint and the unit tests (no network, no secrets). Agents: start with
`CLAUDE.md`. Humans: start with `docs/README.md`.
## License
GPL-3.0, see `LICENSE`.
TDQS
Scored across 6 tools
Most tools have distinct purposes: list_properties, get_booking (by id), changes_since, and smoobu_health are clearly separable. The main soft spot is get_bookings vs stays_in_month, which both target bookings within a month but differ by arrival-window vs overlap/pro-rated revenue convention; descriptions do enough to disambiguate but an agent could still hesitate.
All names use snake_case consistently, and list_properties/get_bookings/get_booking follow a clean verb_noun pattern. changes_since, stays_in_month, and smoobu_health deviate into noun/prepositional phrasing, which is a minor inconsistency but still readable and predictable enough.
Six tools is well-scoped for a booking extraction/audit server; each tool covers a distinct operation (enumerate properties, query bookings, fetch detail, diff changes, monthly analytics, health check). Nothing feels redundant or padded.
For a read-only extraction/reporting surface, coverage is good: properties, ranged and per-booking retrieval, change detection, monthly revenue analytics, and account health are all present with no obvious dead ends. Write/update operations are absent, but that appears intentional for this audit-oriented domain.