<div align="center">

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

</div>

---

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?

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.