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

Category	Tools
🔍 Search & discovery	`search_homes` · `get_home` · `get_home_calendar` · `get_recommendations` · `list_my_homes` · `list_favorites` · `add_favorite` · `remove_favorite` · `list_saved_searches` · `get_user_profile`
💬 Messaging	`list_conversations` · `get_conversation` · `send_message` · `start_conversation`

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.

Parameter	Type	Required	Default	Description
`location`	string	No	—	City, region, or country
`checkin`	string	No	—	`YYYY-MM-DD`
`checkout`	string	No	—	`YYYY-MM-DD`
`guests`	number	No	—	Number of guests
`exchange_type`	string	No	—	`GuestPoints` · `simultaneous` · `non_simultaneous`
`home_type`	string	No	—	`house` · `apartment` · `other`
`limit`	number	No	`20`	Results per page (max 36)
`offset`	number	No	`0`	Pagination offset

`get_home`

Full details for a listing.

Parameter	Type	Required	Description
`home_id`	string	Yes	Numeric home ID

`get_home_calendar`

Availability calendar — blocked and open dates for a home.

Parameter	Type	Required	Description
`home_id`	string	Yes	Numeric home ID

`get_recommendations`

Personalised picks based on your profile and history.

Parameter	Type	Required	Default	Description
`limit`	number	No	`8`	Number of results

`list_my_homes`

Your own listings. No parameters.

`list_favorites`

Your saved homes.

Parameter	Type	Required	Default	Description
`limit`	number	No	`20`	Number of results

`add_favorite`

Save a home to your favourites.

Parameter	Type	Required	Description
`home_id`	string	Yes	Home ID

`remove_favorite`

Remove a home from your favourites.

Parameter	Type	Required	Description
`home_id`	string	Yes	Home ID

`list_saved_searches`

Your saved search filters.

Parameter	Type	Required	Default	Description
`limit`	number	No	`100`	Number of results

`get_user_profile`

A member's public profile.

Parameter	Type	Required	Description
`user_id`	string	Yes	Numeric user ID

💬 Messaging

`list_conversations`

Your conversation inbox.

Parameter	Type	Required	Default	Description
`filter`	string	No	`ALL`	`ALL` · `UNANSWERED` · `ARCHIVED`
`limit`	number	No	`20`	Threads to return
`after`	string	No	—	Pagination cursor from previous response

`get_conversation`

All messages in a thread.

Parameter	Type	Required	Description
`conversation_id`	string	Yes	Conversation ID

`send_message`

Reply in an existing conversation.

Parameter	Type	Required	Description
`conversation_id`	string	Yes	Conversation ID
`text`	string	Yes	Message text

`start_conversation`

Open a new conversation about a home.

Parameter	Type	Required	Description
`home_id`	string	Yes	The home you're enquiring about
`text`	string	Yes	Opening message

Scripts

Script	Description
`npm run login`	Capture auth session via browser ← start here
`npm run mcp`	Start the local MCP server
`npm run record`	Full network recorder with HAR capture (API exploration)
`npm run analyze`	Analyze a `.har` file → `api-map.json`
`npm run build`	Compile TypeScript
`npm run check`	Typecheck + lint

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?

Fork the repo and create a branch from main
Make your changes — keep commits conventional (fix:, feat:, chore: etc.)
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.

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github		.github
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
release.config.mjs		release.config.mjs
sonar-project.properties		sonar-project.properties
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🏠 homeexchange-mcp

What you can do

How it works

Quick start

1. Install

2. Capture your session

3. Start the MCP server

Client setup

Claude Desktop

Claude Code

Cursor

Zed

Tool reference

🔍 Search & discovery

search_homes

get_home

get_home_calendar

get_recommendations

list_my_homes

list_favorites

add_favorite

remove_favorite

list_saved_searches

get_user_profile

💬 Messaging

list_conversations

get_conversation

send_message

start_conversation

Scripts

Project layout

Roadmap

Contributing

Disclaimer

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`search_homes`

`get_home`

`get_home_calendar`

`get_recommendations`

`list_my_homes`

`list_favorites`

`add_favorite`

`remove_favorite`

`list_saved_searches`

`get_user_profile`

`list_conversations`

`get_conversation`

`send_message`

`start_conversation`

Packages