stayport

stayport

stayport talks to a Hostex property-management account from the terminal and from MCP clients: properties and room types, reservations (including direct-booking creation, cancellation, lock codes, and per-stay custom fields), availability, guest conversations, reviews, webhooks, listing calendars and prices, custom channels, and income methods. One binary serves a command-line interface and a stdio MCP server, exposing the same 23 operations as hostex_* tools.

Two credentials are involved. Every v3 API call sends a Hostex-Access-Token header whose value comes from the HOSTEX_ACCESS_TOKEN environment variable; calls go to https://api.hostex.io/v3 unless HOSTEX_API_URL overrides the base URL. When the token is not set, commands fail with an error that names the env var — stayport never invents a result. The guest-review operation is the one exception to the token flow: it posts through the Hostex web app, so it logs in with HOSTEX_EMAIL and HOSTEX_PASSWORD (optionally overriding the web base URL, default https://hostex.io/api, with HOSTEX_WEB_API_URL) and fails the same honest way when they are unset.

A v3 call counts as successful only when the response envelope reports error_code 200; the envelope's data is what you get back. Any other envelope is an error carrying the upstream error_msg and request_id.

Install

npx @reneturcios/stayport properties

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/stayport

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead, and pass the env vars above with -e so the server can reach your account.

CLI

export HOSTEX_ACCESS_TOKEN=...   # from your Hostex account settings

stayport properties --limit 10
stayport room-types
stayport reservations --status accepted --start-check-in-date 2026-11-01
stayport create-reservation --property-id 123 --custom-channel-id 9 \
  --check-in-date 2026-11-10 --check-out-date 2026-11-12 \
  --guest-name "Ada Lovelace" --currency USD --rate-amount 20000 \
  --commission-amount 1000 --received-amount 20000 --income-method-id 3
stayport cancel-reservation RES-123
stayport update-lock-code STAY-9 4321
stayport get-custom-fields STAY-9
stayport update-custom-fields STAY-9 '{"gate_code":"88"}'
stayport availabilities --property-ids 1,2 --start-date 2026-11-01 --end-date 2026-11-07
stayport update-availabilities --property-ids 1,2 --available false --dates 2026-11-03
stayport conversations --limit 5
stayport conversation conv-9
stayport send-message conv-9 --message "Welcome! Check-in is at 3pm."
stayport reviews --property-id 123
stayport create-review RES-123 --score 5 --content "Great guest"
stayport webhooks
stayport create-webhook https://example.com/hook
stayport delete-webhook 17
stayport listing-calendar --start-date 2026-11-01 --end-date 2026-11-30 \
  --listings '[{"channel_type":"airbnb","listing_id":"L1"}]'
stayport update-listing-prices --channel-type airbnb --listing-id L1 \
  --prices '[{"date":"2026-11-05","price":15000}]'
stayport custom-channels
stayport income-methods

stayport --version

The guest-review command additionally needs the web-app login:

export [email protected]
export HOSTEX_PASSWORD=...
stayport post-guest-review --reservation-order-code 0-ABC123-xyz \
  --content "Lovely stay" --recommend 1 --overall-rating 5 \
  --cleanliness 4 --respect-of-house-rules 5 --communication 5

Successful commands print the response data as JSON. Exit codes: 0 on success, 1 when a call fails (missing credential, upstream envelope error, network failure), 2 for usage errors. Amounts on reservation creation are in cents, exactly as the Hostex API takes them; listing prices are passed through in the shape the API expects.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/stayport mcp

MCP client configuration:

{
  "mcpServers": {
    "stayport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/stayport", "mcp"],
      "env": {
        "HOSTEX_ACCESS_TOKEN": "..."
      }
    }
  }
}

Add HOSTEX_EMAIL and HOSTEX_PASSWORD to that env block if you want the guest-review tool to work; the other 22 tools only need the access token.

Tools

Tool	Input	What it does
hostex_list_properties	offset, limit, id (all optional)	Lists properties with ID, title, address, channels, and coordinates.
hostex_list_room_types	offset, limit (optional)	Lists room types.
hostex_list_reservations	reservation_code, property_id, status, check-in/out date bounds, order_by, offset, limit (all optional)	Lists and searches reservations.
hostex_create_reservation	property_id (string), custom_channel_id, check_in_date, check_out_date, guest_name, currency, rate_amount, commission_amount, received_amount, income_method_id (required); number_of_guests, email, mobile, remarks (optional)	Creates a direct booking. Amounts are in cents.
hostex_cancel_reservation	reservation_code	Cancels a direct booking (channel bookings are not supported).
hostex_update_lock_code	stay_code, lock_code	Sets a stay's lock code.
hostex_get_custom_fields	stay_code	Reads a stay's custom fields.
hostex_update_custom_fields	stay_code, custom_fields (object)	Writes a stay's custom fields, usable in automated messages as {{cf.field_name}}.
hostex_list_availabilities	property_ids (comma-separated string), start_date, end_date	Queries availability for a date range.
hostex_update_availabilities	property_ids (number array), available; start_date, end_date, dates (optional)	Sets availability for dates or a range.
hostex_list_conversations	offset, limit (optional)	Lists guest conversations and inquiries.
hostex_get_conversation	conversation_id	Gets a conversation with all its messages.
hostex_send_message	conversation_id; message, jpeg_base64 (optional)	Sends a text or JPEG image message to the guest.
hostex_list_reviews	reservation_code, property_id, review_status, check-out date bounds, offset, limit (all optional)	Queries reviews with filters.
hostex_create_review	reservation_code; host_review_score, host_review_content, host_reply_content (optional)	Creates a review or a reply for a reservation.
hostex_post_guest_review	reservation_order_code, content, recommend ("0"/"1"), overall_rating, cleanliness, respect_of_house_rules, communication ("1"–"5"); three optional *_content notes	Posts a full guest review through the web app; needs the email/password login.
hostex_list_webhooks	(none)	Lists configured webhooks.
hostex_create_webhook	url	Creates a webhook.
hostex_delete_webhook	webhook_id	Deletes a manageable webhook.
hostex_get_listing_calendar	start_date, end_date, listings ({channel_type, listing_id} array)	Gets calendar information for multiple listings.
hostex_update_listing_prices	channel_type, listing_id, prices ({date, price} array)	Updates listing prices.
hostex_list_custom_channels	(none)	Lists custom channels from the Custom Options Page.
hostex_list_income_methods	(none)	Lists income methods from the Custom Options Page.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.