homes-mcp

MCP server for homes.com — natural-language access to listings, property records, price/tax history, market reports, saved homes/searches, and photo galleries. Routes through your signed-in homes.com tab via the fetchproxy browser extension, so AWS WAF sees a real browser session instead of a Node process.

• npm: npmjs.com/package/homes-mcp
• Source: github.com/chrischall/homes-mcp

⚠️ homes.com does not publish a public consumer API. This server reads the Schema.org JSON-LD blob (and some DOM-side sections) embedded in each SSR page, dispatched through your own signed-in browser tab via the fetchproxy extension. Use at your own discretion.

Setup

1. Install homes-mcp

.mcp.json (project) or ~/.claude/mcp.json (global):

{
  "mcpServers": {
    "homes": {
      "command": "npx",
      "args": ["-y", "homes-mcp"]
    }
  }
}

2. Install the fetchproxy extension (one-time, shared across all fetchproxy-based MCPs)

The extension lives in its own repo and is installed separately — it is not bundled in this repo. Follow the install instructions at github.com/chrischall/fetchproxy, then load the built extension in Chrome via chrome://extensions → Developer mode → Load unpacked.

3. Open homes.com and sign in.

That's it. No API keys, no env vars. (Sign-in isn't strictly required for the public-listing tools, but having a real session active helps the page render the way the extractors expect — and saved-homes / saved-searches require it.)

Tools

Search & resolve

• homes_search_properties — Search by free-text location (city, ZIP, neighborhood). Slugifies the input into homes.com's URL routing. Filters by property_type, listing_type, sort, and a price_min/price_max band (homes.com's ?price-min=/?price-max= query facet). Returns each listing's address, price, beds/baths, sqft, primary photo, listing agent + brokerage. Caps at the ~40-listing SSR page; sets truncated/total_estimated when the market has more.
• homes_get_by_address — Resolve a single US street address to its canonical homes.com property URL + opaque property hash. Walks structured smartsearch typeahead → slug routing → city/zip search-fallback, verifying each candidate with a whole-token street + unit match. Returns matched_via and degrades gracefully to { resolved: false }.
• homes_resolve_addresses — Bulk version of homes_get_by_address (up to 100 addresses, input order preserved, per-row outcomes). Prefer for any batch ≥ 3.

Property details

• homes_get_property — Full record for a property by URL. Parses JSON-LD + DOM-side sections: address, lat/lng, beds/baths, sqft, year built, price, status, listing agent + brokerage, highlights, schools, HOA (raw + normalized monthly), lot size (sqft + derived acres), parking, heating/cooling, MLS id/source, tax, days-on-market, price drops, and server-derived extracted_features. Optional inline price_history / tax_history.
• homes_get_property_photos — Full photo gallery scraped from <img> tags on the detail page (JSON-LD carries only one image). Returns { url, position, alt? } per photo, filtered to the homes.com CDN.
• homes_bulk_get — Fetch up to 200 properties' structured records in one call (per-row errors captured, input order preserved). Use instead of looping when you just want the records.
• homes_compare_properties — Side-by-side comparison of 2–8 properties with an aligned summary table. Concurrent fetches, per-row errors.
• homes_get_nearby_listings — The "Homes for Sale Near This Property" cross-link cards from a detail page (For Sale, optionally Rentals). URL + address only.

History & market

• homes_get_history — Combined price + tax history in one fetch: listing_events, ownership_events, lien_events, cross-MCP-normalized events_normalized, and tax_records. (Preferred over the two split tools below.)
• homes_get_property_history — Deprecated — price/ownership/lien timelines only. Prefer homes_get_history.
• homes_get_tax_history — Deprecated — year-by-year tax records only. Prefer homes_get_history.
• homes_get_market_report — Median / average / $-per-sqft for a market, derived from the sold search page's JSON-LD.

Saved (auth-gated)

• homes_get_saved_homes — The signed-in user's saved (favorited) homes. Requires an authenticated homes.com tab.
• homes_get_saved_searches — The signed-in user's saved searches. Requires an authenticated homes.com tab.

Local calculators (no network)

• homes_calculate_mortgage — Local PITI calculator (price, rate, down payment, taxes, insurance, HOA, PMI → monthly breakdown).
• homes_calculate_affordability — Local affordability calculator — max purchase price under standard 28/36 DTI.
• homes_estimate_rent_vs_buy — Local rent-vs-buy model. You must supply monthly_rent — homes.com publishes no rental estimate to impute it (see Gotchas).

Diagnostics & sessions

• homes_healthcheck — Round-trips /robots.txt through the fetchproxy bridge; distinguishes "bridge down" vs "extension not connected" vs "homes.com-side problem."
• homes_get_session_context, homes_register_session, homes_set_active_session — List / register / switch logical homes.com sessions.

Trigger examples

• "Find me condos for sale in Atlanta under $500k on homes.com" → homes_search_properties (with price_max)
• "Resolve 3199 Delmar Ln NW, Atlanta GA to a homes.com listing" → homes_get_by_address
• "What's the price history for this homes.com listing?" → homes_get_history (or homes_get_property with include_price_history)
• "Show me all photos for this homes.com listing" → homes_get_property_photos
• "What's the market report for sold homes in Brooklyn?" → homes_get_market_report
• "List my saved homes on homes.com" → homes_get_saved_homes
• "Monthly payment on a $500k home, 20% down, 6.5% rate" → homes_calculate_mortgage

Gotchas

• AWS WAF challenge. homes.com (CoStar) gates traffic through AWS WAF and occasionally serves a challenge page to fresh sessions. Solving it in the Chrome tab once unblocks subsequent fetches; the client detects the interstitial and throws SessionNotAuthenticatedError.
• No write surface. All tools are read-only. Saving a home / contact forms are not implemented.
• Property URL is required for detail tools. get_property, get_property_photos, compare_properties, history, photos, and nearby all need a full property URL from a search or get_by_address result — there's no stable way to construct one from a property id alone.
• No rental estimate to impute. homes.com publishes no rent_zestimate analogue, so homes_estimate_rent_vs_buy requires you to pass monthly_rent. For a rent figure to plug in, use a sibling MCP (zillow_get_property carries rent_zestimate; redfin_get_comparable_rentals returns rental comps).