Skip to main content
Glama
homeexchange-mcp

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.

License: MIT Node TypeScript MCP SDK

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, then he_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.js

Claude Code

claude mcp add homeexchange \
  --env HE_ACCESS_TOKEN=your_token \
  -- node /absolute/path/to/homeexchange-mcp/dist/bundle.js

Claude 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.

  1. Log in to homeexchange.com

  2. DevTools → Application → Cookies → homeexchange.com

  3. Copy the value of oidc_access_token → set it as HE_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

HE_ACCESS_TOKEN

one auth method*

JWT from the oidc_access_token cookie

HE_COOKIES

one auth method*

Full cookie string; enables auto-renewal if PHPSESSID is included

* 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

he_get_home, he_get_calendar, he_update_calendar

👤 Users

3

he_get_user, he_get_user_ratings

❤️ Favorites

7

he_get_favorites, he_add_favorite, he_create_wishlist

💬 Conversations & messages

14

he_get_conversations, he_send_message, he_send_first_message

🔄 Exchanges

8

he_get_my_exchanges, he_change_exchange_type, he_rate_home

🔍 Search & subscription

7

he_search_homes, he_get_saved_searches

🔐 Auth utilities

4

he_auth_status, he_set_tokens

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 PHPSESSID auto-renewal is configured

  • No image upload for property/profile photos (multipart not implemented yet)

  • No property creation — POST /v1/homes is not exposed

  • Conversation pagination is handled client-side (the v3 API ignores the after cursor)

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.js

Full tool reference, search-filter format and architecture: docs/TOOLS.md.

License

MIT

Available Tools

52 tools
he_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_wishlistA

Create a new favorites folder (wishlist). IMPORTANT: ask user confirmation.

Inputs: name (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_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

    A3.7/5.0

    Scored across 52 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      3
      1
      MIT