homeexchange-mcp
HomeExchange MCP
MCP server for HomeExchange — browse listings, manage your calendar, send messages and track exchanges from your AI assistant, in natural language.
Installation · Tools · Examples · Limitations · 🇫🇷 Français
Overview
This MCP server exposes the HomeExchange platform as 52 tools your assistant can call. Ask in natural language, it executes:
You: Find houses in Mallorca available Aug 5–19 with a pool and at least 2 bedrooms, then show my unread conversations.
Assistant: (calls
he_search_homes, thenhe_get_conversations) 7 matching homes in Mallorca — top pick: a verified 3-bedroom villa with pool, 92 % response rate. You have 2 unread conversations: Marta (Palma) and Lluís (Sóller).
Related MCP server: PeopleLikeUs MCP Server
Requirements
Node.js ≥ 18
A HomeExchange account with an active subscription
Any MCP client — Claude Code, Claude Desktop, Cursor, Windsurf…
Installation
Not published to npm — run from the local bundle:
git clone https://github.com/manganate006/homeexchange-mcp
cd homeexchange-mcp
npm install && npm run bundle # → dist/bundle.jsClaude Code
claude mcp add homeexchange \
--env HE_ACCESS_TOKEN=your_token \
-- node /absolute/path/to/homeexchange-mcp/dist/bundle.jsClaude Desktop / Cursor
Add to claude_desktop_config.json (or your client's MCP config):
{
"mcpServers": {
"homeexchange": {
"command": "node",
"args": ["/absolute/path/to/homeexchange-mcp/dist/bundle.js"],
"env": { "HE_ACCESS_TOKEN": "eyJ..." }
}
}
}Authentication
⚠️ No automated login. HomeExchange uses Auth0 with AWS WAF CAPTCHA + Cloudflare Turnstile, which block automated sessions. You paste a token from your browser once.
Log in to homeexchange.com
DevTools → Application → Cookies →
homeexchange.comCopy the value of
oidc_access_token→ set it asHE_ACCESS_TOKEN
The token lasts ~24 h and is cached at ~/.homeexchange-mcp-tokens.json. Provide the full cookie string via HE_COOKIES (including PHPSESSID) to enable automatic renewal — no manual step afterwards.
Variable | Required | Purpose |
| one auth method* | JWT from the |
| one auth method* | Full cookie string; enables auto-renewal if |
* At least one of HE_ACCESS_TOKEN / HE_COOKIES, or inject at runtime with he_set_tokens. Rate-limit tuning (HE_READ_DELAY, HE_WRITE_DELAY, HE_MESSAGE_DELAY, HE_WEB_VERSION) and the full auth priority: see docs/TOOLS.md.
Tools
52 tools, he_ prefix. Summary by domain — full parameters in docs/TOOLS.md.
Domain | Tools | Examples |
🏠 Properties | 9 |
|
👤 Users | 3 |
|
❤️ Favorites | 7 |
|
💬 Conversations & messages | 14 |
|
🔄 Exchanges | 8 |
|
🔍 Search & subscription | 7 |
|
🔐 Auth utilities | 4 |
|
Examples
"Search houses in Mallorca available August 5–19 with pool and 2+ bedrooms"
"Show my unread conversations"
"Translate the last message from conversation 12345 to French"
"Mark my calendar unavailable July 15 – August 20"
"First-contact the owner of home 98765 for Sept 1–8, 4 guests"
"Switch the exchange in conversation 11111 to reciprocal"
Limitations
Manual token every ~24 h, unless
PHPSESSIDauto-renewal is configuredNo image upload for property/profile photos (multipart not implemented yet)
No property creation —
POST /v1/homesis not exposedConversation pagination is handled client-side (the v3 API ignores the
aftercursor)
Development
npm run dev # tsc watch
npm run build # compile TypeScript
npm run bundle # single-file dist/bundle.js (fast startup)
npx @modelcontextprotocol/inspector node dist/bundle.jsFull tool reference, search-filter format and architecture: docs/TOOLS.md.
License
Available Tools
52 toolshe_add_favoriteA
Add a property to favorites. Optionally specify a wishlist folder. IMPORTANT: ask user confirmation.
Inputs: homeId (required), wishlistId.
he_archive_conversationA
Archive a conversation. IMPORTANT: ask user confirmation.
Inputs: conversationId (required).
he_auth_statusA
Check the current authentication status (logged in, token expiry, token source)
Inputs: no named parameters.
he_batch_archiveA
Archive multiple conversations at once. IMPORTANT: ask user confirmation.
Inputs: conversationIds (required).
he_cancel_exchangeA
Cancel an exchange with a reason. IMPORTANT: ask user confirmation.
Inputs: reason (required), conversationId (required).
he_change_exchange_homeA
Change which home is proposed in an exchange. Use the exchange ID (not conversation ID) where you are the host. Get the exchange ID from conversation details (all_exchanges array, find the one where host=you). IMPORTANT: ask user confirmation.
Inputs: homeId (required), exchangeId (required).
he_change_exchange_typeA
Confirm/switch an exchange to reciprocal. Only needs the conversation ID: the correct home is auto-derived from the home already attached to your side of the conversation (passing a wrong home ID returns HTTP 500). senderHomeId is an optional hint, only used as a fallback when no home of yours is attached yet (pure GuestPoints conversation). IMPORTANT: ask user confirmation.
Inputs: conversationId (required), senderHomeId.
he_create_saved_searchA
Create a saved search from search filters. IMPORTANT: ask user confirmation.
Inputs: searchData (required).
he_create_wishlistA
Create a new favorites folder (wishlist). IMPORTANT: ask user confirmation.
Inputs: name (required).
he_delete_saved_searchA
Delete a saved search. IMPORTANT: ask user confirmation.
Inputs: searchId (required).
he_favorite_conversationA
Mark or unmark a conversation as favorite (star). IMPORTANT: ask user confirmation.
Inputs: conversationId (required), favorite.
he_get_calendarA
Get availability calendar for a single property. ⚠️ For multiple homes, use he_get_calendar_batch instead to avoid repeated calls.
Inputs: homeId (required).
he_get_calendar_batchA
Get availability calendars for multiple properties in one call. Prefer this over calling he_get_calendar repeatedly. Max 20 homes.
Inputs: homeIds (required).
he_get_cancellation_reasonsA
Get the list of valid exchange cancellation reasons
Inputs: no named parameters.
he_get_conversationA
Get detailed info about a single conversation (participants, exchanges, stay requests)
Inputs: conversationId (required).
he_get_conversationsA
Get the user's conversations list with pagination. Returns conversation metadata, last message preview, exchange details
Inputs: after, first, fields, filter.
he_get_conversation_statsA
Get conversation statistics (unread count, total count)
Inputs: no named parameters.
he_get_favoritesA
Get the list of property IDs saved as favorites by the authenticated user
Inputs: no named parameters.
he_get_favorites_fullA
Get favorites with full property details (not just IDs). Paginated.
Inputs: page, limit.
he_get_homeA
Get full details of a HomeExchange property (name, location, GPS, features, photos, owner info, descriptions, amenities). Descriptions include every language the owner wrote; pass locale to keep only one and save tokens.
Inputs: homeId (required), locale.
he_get_home_descriptionsA
Get a property's description texts by language, compact (title, good_feature, good_place, other per locale). Flags is_fallback when a requested language has no translation. Single API call — cheaper than he_get_home for comparing languages.
Inputs: homeId (required), locales.
he_get_last_searchesB
Get search history (last searches performed)
Inputs: no named parameters.
he_get_messagesA
Get messages from a specific conversation. Supports pagination via limit/offset.
Inputs: conversationId (required), limit, offset.
he_get_messages_configA
Get messages configuration (templates, auto-messages settings)
Inputs: no named parameters.
he_get_my_exchangesA
Get the user's exchanges (upcoming, ongoing, or past) with pagination
Inputs: limit, filter, offset.
he_get_my_homesA
Get all properties owned by the authenticated user
Inputs: no named parameters.
he_get_ratingsB
Get reviews and ratings for a HomeExchange property (cleanliness, expectations, communication scores, feedback text)
Inputs: homeId (required).
he_get_saved_searchB
Get details of a specific saved search
Inputs: searchId (required).
he_get_saved_searchesA
Get all saved searches
Inputs: no named parameters.
he_get_subscriptionA
Get the user's subscription plan info (type, expiry, auto-renew status)
Inputs: no named parameters.
he_get_userB
Get a HomeExchange user's profile (name, verified status, number of exchanges, response rate, images)
Inputs: userId (required).
he_get_user_achievementsB
Get a user's GuestPoints loyalty level and achievements
Inputs: userId (required).
he_get_user_ratingsB
Get reviews/ratings about a user (as host and guest)
Inputs: userId (required), limit.
he_get_who_favorited_meB
Get users/homes that have favorited one of your properties (homecards). Useful to find potential exchange partners.
Inputs: homeId (required), page, limit.
he_get_wishlistsB
Get favorite folders (wishlists) with pagination
Inputs: page, limit.
he_pre_approve_exchangeA
Pre-approve an exchange request. IMPORTANT: ask user confirmation.
Inputs: conversationId (required).
he_rate_homeA
Rate a home after an exchange (clean, expectation, communication: 1-5). IMPORTANT: ask user confirmation.
Inputs: clean (required), expectation (required), communication (required), conversationId (required), +1 more.
he_refresh_tokenA
Manually trigger a token refresh using the stored PHPSESSID session cookie. Useful to test auto-renewal or force a new token before expiry. Only works if HE_COOKIES was used with a PHPSESSID value.
Inputs: no named parameters.
he_remove_favoriteA
Remove a property from favorites. IMPORTANT: ask user confirmation.
Inputs: homeId (required).
he_search_conversationsC
Search through conversations by keyword
Inputs: query (required).
he_search_homesA
Search for homes/properties. Returns slimmed results (id, location, bedrooms, rating, owner, cover image).
⚠️ IMPORTANT: If you pass calendar.date_ranges in filters, results are ALREADY filtered by availability — do NOT call he_get_calendar on each result, it is redundant and wastes tokens. Only call he_get_calendar when you need the full availability breakdown of a specific home.
Full example with all filter categories: { "location": { "bounds": { "sw": { "lat": 36.0, "lon": -9.5 }, "ne": { "lat": 43.8, "lon": 4.3 } } }, "guests_nb": 4, "home": { "type": "home", "size": { "bedrooms": 2, "bathrooms": 1 }, "amenities": ["swimming-pool", "a-c", "wifi"], "surrounding": ["seaside"], "is_primary": true, "is_private_room": false, "exclude_animals": ["cat", "dog"] }, "calendar": { "date_ranges": [{ "from": "2026-08-05", "to": "2026-08-19" }] }, "exchange_type": "reciprocal", "filters": ["home-verified", "response-rate-above-threshold"] }
Filter reference
location: bounds {sw/ne with lat/lon} or location_id (Jawg polygon)
home.type: "home" (maison) | "flat" (appartement)
home.is_private_room: false (logement entier) | true (chambre privée)
home.is_primary: true (résidence principale) | false (résidence secondaire)
home.surrounding (array): "countryside" | "mountains" | "seaside" | "lakes" | "cities" | "villages" | "isolated" | "island"
home.amenities (array):
Essentials: "heating-system" | "dishwasher" | "washing-machine" | "dryer" | "bathtub" | "tv" | "wifi" | "electric-car-plug"
Comfort: "a-c" | "elevator" | "parking-space" | "jacuzzi" | "fireplace" | "gym" | "garden" | "balcony-terrace" | "swimming-pool" | "public-transit-access"
Kids: "baby-bed" | "kids-toys" | "playground" | "baby-gear" | "secured-pool"
Work: "dedicated-workspace" | "high-speed-connexion"
Accessibility: "disabled-access" | "children-welcome" | "pets-welcome" | "smokers-welcome"
home.exclude_animals (array): "cat" | "dog" | "other"
home.eco_level: 4 (maisons durables uniquement)
exchange_type: "available" (all) | "reciprocal" | "guest-wanted" (GuestPoints only)
filters (array): "home-verified" | "response-rate-above-threshold" ← prefer this over min_response_rate param
calendar.date_ranges: [{ "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }] calendar.duration: { "kind": "week-end" | "week" | "month" }
guestpoint_range: { "min": 0, "max": 250 } (GP per night)
Inputs: filters (required), limit, offset, min_response_rate.
he_send_first_messageA
Send a first contact message to a property owner, creating a new conversation. exchange_type: 1=reciprocal, 2=guestpoints (omit to let API decide based on calendar). IMPORTANT: ask user confirmation before sending.
Inputs: endOn (required), homeId (required), content (required), nbGuest (required), +4 more.
he_send_messageB
Send a message in an existing HomeExchange conversation. IMPORTANT: ask user confirmation before sending.
Inputs: content (required), conversationId (required).
he_set_cookiesA
Inject a raw cookie string from the browser. Must contain oidc_access_token (or access_token). Include PHPSESSID to enable automatic token renewal. Get all cookies from DevTools → Application → Cookies → homeexchange.fr
Inputs: cookies (required).
he_set_tokensA
Inject access_token (and optionally refresh_token) for authentication. Get these from browser DevTools → Application → Cookies → homeexchange.fr
Inputs: accessToken (required), refreshToken.
he_translate_messageC
Translate a message to a target language
Inputs: messageId (required), targetLanguage (required).
he_translate_messages_batchC
Translate multiple messages at once
Inputs: messageIds (required), targetLanguage (required).
he_unarchive_conversationB
Unarchive a conversation. IMPORTANT: ask user confirmation.
Inputs: conversationId (required).
he_update_calendarB
Update availability calendar periods for a property. Status: 1=available, 2=unavailable, 3=maybe. IMPORTANT: ask user confirmation.
Inputs: homeId (required), periods (required).
he_update_descriptionA
Update property description texts (title, good_feature, good_place, other). Omitted fields are preserved: current values of the target locale are merged in before the PUT. Use locale to create or update a specific language version. IMPORTANT: ask user confirmation.
Inputs: homeId (required), other, title, locale, +2 more.
he_update_exchange_datesA
Update exchange dates for a conversation. IMPORTANT: ask user confirmation.
Inputs: dates (required), conversationId (required).
he_update_homeA
Update property details (capacity, min_nights, features, etc.). IMPORTANT: ask user confirmation.
Inputs: fields (required), homeId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 52 tools
Each tool has a clearly distinct purpose, with descriptive names and detailed descriptions that explicitly differentiate similar operations (e.g., he_get_home vs he_get_home_descriptions, he_get_calendar vs he_get_calendar_batch). No significant overlap exists.
All tools follow a consistent 'he_verb_noun' pattern in snake_case (e.g., he_get_home, he_search_homes, he_add_favorite). The naming is uniform and predictable across the entire set.
With 52 tools, the set is large and covers many sub-domains (auth, properties, conversations, exchanges, favorites, etc.). While each tool serves a specific purpose, the count feels slightly heavy for an MCP service, but it is justified by the breadth of the platform's functionality.
The tool surface is comprehensive, covering full CRUD for properties, conversations, exchanges, favorites, saved searches, and more. It includes batch operations, translations, authentication management, and configuration, leaving minimal gaps for core home exchange workflows.
Maintenance
Related MCP Connectors
Manage Hostaway listings, reservations, calendar, guest messages, reviews and tasks.
Manage your Hostex vacation rentals—properties, reservations, availability, listings, and guest me…
Manage vacation rentals, bookings, calendars and operations with OAuth and action approvals.
Read rentals, channels, rates and calendar events; create, change and delete bookings in Hosthub.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to interact with Hostaway's property management platform through standardized MCP tools. Provides access to listings, bookings, guest communication, and availability checking for vacation rental management.-
- AlicenseBqualityDmaintenanceEnables AI assistants to browse properties, manage conversations, update availability calendars, and track exchanges on the PeopleLikeUs home exchange platform via natural language, with 28 MCP tools and auto-login support.26MIT
- AlicenseNot gradedqualityBmaintenanceEnables searching homes, reading messages, and managing favourites on HomeExchange via an AI client.3ISC
- AlicenseAqualityDmaintenanceEnables AI agents to search Dutch housing listings on Kamernet.nl, retrieve full listing details, and optionally reply to landlords; designed for personal use in finding rooms, studios, and apartments.31MIT