io.github.uncfreak1255-code/hostaway
Read-only MCP server for Hostaway PMS — guest conversations, reservations, and listings
Open source Open in the app JSON README (API)
About
Read-only MCP server for Hostaway PMS — guest conversations, reservations, and listings
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- uncfreak1255-code
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Open pull requests
- 4
- Last push
- 2026-09-03T13:14:16Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:36
- Updated
- 2026-08-29 04:01:36
- Origin id
io.github.uncfreak1255-code/hostaway
README
# hostaway-mcp
Read-only, hospitality-shaped MCP server for Hostaway.
This repo owns the operator product only: local/npm `stdio`, six read-only
tools, no Cloudflare Worker, and no Seascape booking surface.
## V1 Goal
Make Codex and Claude useful in real Hostaway workflows without hand-wiring raw API
calls every time.
V1 is intentionally narrow:
- read-only only
- hospitality-native tools, not raw endpoint parity
- optimized for conversation context, reservation lookup, and listing lookup
## Exact V1 Surface
- `list_unread_guest_threads`
- `get_conversation_context`
- `get_reservation_brief`
- `get_listing_brief`
- `search_reservations`
- `search_conversations`
## Local Development
```bash
npm install
npm test
npm run check
npm run build
```
Run the stdio server locally:
```bash
HOSTAWAY_API_TOKEN=your-token-here node dist/cli.js
```
Create a local npm package tarball:
```bash
npm pack
```
After publish, run without cloning:
```bash
npx hostaway-mcp
```
## MCP Client Wiring
For local MCP clients, provide `HOSTAWAY_API_TOKEN` through the environment and
spawn the published npm package over stdio.
The snippets below are pinned to the current published version:
```text
hostaway-mcp@0.2.0
```
Update that version intentionally when you upgrade.
### Claude Desktop (macOS)
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`.
If you already have top-level keys like `preferences`, keep them and add
`mcpServers` alongside them:
```json
{
"mcpServers": {
"hostaway": {
"command": "npx",
"args": ["-y", "hostaway-mcp@0.2.0"],
"env": {
"HOSTAWAY_API_TOKEN": "your-token-here"
}
}
}
}
```
Restart Claude Desktop after saving the file.
### Codex
Edit `~/.codex/config.toml` and add:
```toml
[mcp_servers.hostaway]
command = "npx"
args = ["-y", "hostaway-mcp@0.2.0"]
[mcp_servers.hostaway.env]
HOSTAWAY_API_TOKEN = "your-token-here"
```
Verify the server is registered:
```bash
codex mcp list
```
### Local Built CLI
If you want to run the repo checkout instead of npm, point the client at the built
CLI directly:
```json
{
"command": "node",
"args": ["/absolute/path/to/hostaway-mcp/dist/cli.js"],
"env": {
"HOSTAWAY_API_TOKEN": "your-token-here"
}
}
```
## Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| `HOSTAWAY_API_TOKEN` | Yes | — | Hostaway API token used to authenticate all requests. |
| `HOSTAWAY_BASE_URL` | No | Hostaway production URL | Override the API base URL (useful for testing). |
## V1 Non-Goals
- sending guest messages
- mutating reservations or listings
- Cloudflare Worker transport
- Seascape booking/distribution flows
- webhook ingestion
- background sync pipelines
- dashboards or owner reporting
- generic REST-to-MCP proxy coverage
## Source Design
See [`docs/designs/v1-readonly-hostaway-mcp.md`](./docs/designs/v1-readonly-hostaway-mcp.md).