🏠 homeexchange-mcp

An unofficial MCP server for HomeExchange

Search homes · Read messages · Manage favourites · All from your AI client

Unofficial project. Not affiliated with or endorsed by HomeExchange SAS. Personal use only — see disclaimer.

What you can do

Once connected, ask your AI client things like:

• "Find homes in Lisbon for 2 guests in July, GuestPoints only"

• "Show me my unanswered messages"

• "Send a message to conversation 12345 asking about parking"

• "What homes have I favourited?"

• "Show the availability calendar for home 1950607"

14 tools across two categories:

Related MCP server: Homey MCP Server

How it works

  npm run login
       │
  Browser opens → you log in once
       │
  session.json  (token + cookies, stays local)
       │
  npm run mcp
       │
  MCP Server (local, stdio)
       │
  ┌────┴──────────────────────┐
  │                           │
  search & discovery     messaging
  (10 tools)             (4 tools)
       │                      │
       └─────────┬────────────┘
                 │
     api.homeexchange.com
     bff.homeexchange.com

Auth is captured once via your real browser session — no credentials stored in code. The MCP server runs locally and makes direct API calls on your behalf. Works with any MCP-compatible client.

Quick start

1. Install

npm install
npx playwright install chromium

2. Capture your session

npm run login

A browser opens. Log in to HomeExchange, then press Ctrl+C. Your session is saved locally to session.json (git-ignored).

Tokens expire after a few days. Re-run npm run login when tools start returning 401s.

3. Start the MCP server

npm run mcp

Client setup

Works with any MCP client that supports stdio transport.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "homeexchange": {
      "command": "npx",
      "args": ["ts-node", "src/mcp.ts"],
      "cwd": "/path/to/homeexchange-mcp"
    }
  }
}

Claude Code

claude mcp add homeexchange -- npx ts-node src/mcp.ts

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "homeexchange": {
      "command": "npx",
      "args": ["ts-node", "src/mcp.ts"],
      "cwd": "/path/to/homeexchange-mcp"
    }
  }
}

Zed

.zed/settings.json:

{
  "context_servers": {
    "homeexchange": {
      "command": { "path": "npx", "args": ["ts-node", "src/mcp.ts"] }
    }
  }
}

Tool reference

🔍 Search & discovery

search_homes

Search listings by location, dates, guests, and exchange type.

get_home

Full details for a listing.

get_home_calendar

Availability calendar — blocked and open dates for a home.

get_recommendations

Personalised picks based on your profile and history.

list_my_homes

Your own listings. No parameters.

list_favorites

Your saved homes.

add_favorite

Save a home to your favourites.

remove_favorite

Remove a home from your favourites.

list_saved_searches

Your saved search filters.

get_user_profile

A member's public profile.

💬 Messaging

list_conversations

Your conversation inbox.

get_conversation

All messages in a thread.

send_message

Reply in an existing conversation.

start_conversation

Open a new conversation about a home.

Scripts

Project layout

src/
  login.ts          browser auth capture
  record.ts         full network recorder with HAR output
  analyze.ts        HAR → api-map.json analysis
  api.ts            authenticated HTTP client
  mcp.ts            MCP stdio server
  tools/
    search.ts       10 search & discovery tools
    messaging.ts    4 messaging tools

Roadmap

Tracked as GitHub Issues — upvote or comment to influence priority:

• #9 Calendar integration — query and update availability, surface conflicts across requests

• #10 Remote MCP — hosted endpoint, no local setup required

• #11 Token expiry detection — auto-prompt on 401 (good first issue)

• #12 Saved search alerts — notify when new homes match your saved searches

Contributing

Ideas, bug reports, and pull requests are welcome.

Got a feature idea or found a bug? Open an issue — describe what you were trying to do and what happened (or didn't).

Want to contribute code?

1. Fork the repo and create a branch from main

2. Make your changes — keep commits conventional (fix:, feat:, chore: etc.)

3. Open a pull request — CI must pass before merge

Good first issues are tagged good first issue — start there if you're new to the codebase.

Note: This project reverse-engineers a private API. New tools may break if HomeExchange changes their endpoints. Please check existing issues before reporting an API breakage.

Disclaimer

This is an unofficial, community project with no affiliation with HomeExchange SAS.

• Uses your own HomeExchange account credentials, exactly as your browser does

• Personal, non-commercial use only — not for scraping, reselling, or commercial exploitation of HomeExchange data

• Subject to HomeExchange's Terms of Service

• The HomeExchange API is private and undocumented — endpoints may change without notice

The intent is to build a genuinely useful tool for the HomeExchange community, and ideally to partner with HomeExchange to do this officially. If you work at HomeExchange and are interested in collaborating on a proper integration, please open an issue or get in touch.

License

MIT — personal and non-commercial use.

HomeExchange® is a registered trademark of HomeExchange SAS. This project is independent and not endorsed by HomeExchange SAS.