🏠 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"

20 tools across three categories:

Related MCP server: Homebox 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 &       messaging          users
  discovery      (8 tools)        (3 tools)
  (9 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.

Optional location search configuration

Searching homes by a place name needs a personal geocoding token to resolve that name to a HomeExchange search location. Use .env.example as a reference, then export HOMEEXCHANGE_GEOCODING_TOKEN before starting the MCP server. Keep the token out of version control.

3. Start the MCP server

npm run mcp

Local MCP testing

The project includes a local end-to-end smoke test. It builds the server, starts it over stdio, performs the MCP handshake, and confirms that all tools are available. It does not need a HomeExchange session and makes no network requests.

npm run test:mcp

To run the built server in the same form used by the smoke test:

npm run mcp:local

After completing npm run login, you can also validate one read-only HomeExchange call without displaying any account data:

npm run test:mcp -- --live

The live check calls list_my_homes. Do not use it for testing changes that write data, and never commit session.json or .env.

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.

💬 Messaging

list_conversations

Your conversation inbox.

get_conversation

Extended information about a conversation, including exchange details.

get_messages

All messages in a conversation thread.

get_exchange_request

Exchange request details attached to a conversation.

send_message

Reply in an existing conversation.

start_conversation

Open a new conversation about a home.

pre_approve_exchange

Pre-approve an exchange request.

archive_conversation

Archive a conversation.

👤 Users

get_user_profile

A member's public profile.

get_user_ratings

Ratings left for a member.

get_user_achievements

Achievements earned by a member.

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       9 search & discovery tools
    messaging.ts    8 messaging tools
    user.ts         3 user 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 with a conventional title, such as feat: add calendar filtering or fix(api): handle expired sessions

4. Ensure all required checks 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.

Releases

Release Please collects conventional commits on main into a release pull request. A maintainer reviews that pull request and merges it when the project is ready to publish. Merging it updates CHANGELOG.md, package.json, and package-lock.json, then creates the version tag and GitHub Release.

Before 1.0.0, feat: and breaking changes increase the minor version, while fix:, perf:, and revert: increase the patch version. The release workflow consumes the organization Actions secret named RELEASE_TOKEN so its pull requests receive the normal required CI checks. Organization administrators must include this repository in the secret's selected-repository access policy. The underlying credential needs permission to write contents and pull requests, and an expiration that complies with organization policy.

Pull request titles are validated against the Conventional Commits format. Squash merges use the validated title as the commit subject so Release Please can calculate the correct version and changelog entry.

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.