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, 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).

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.

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

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