{
  "markdown": "# homes-mcp\n\n[![CI](https://github.com/chrischall/homes-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/homes-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/homes-mcp)](https://www.npmjs.com/package/homes-mcp)\n[![license](https://img.shields.io/npm/l/homes-mcp)](LICENSE)\n\nhomes.com real-estate access as an MCP server for Claude — search listings, resolve addresses, fetch property details, price/tax history, market reports, saved homes, photo galleries, and run affordability/mortgage math, all via natural language.\n\n> ⚠️ homes.com does not publish a public consumer API. This server reads the same server-rendered HTML and Schema.org JSON-LD that homes.com itself ships to your browser, routed through your own signed-in browser tab via the [fetchproxy](https://github.com/chrischall/fetchproxy) extension. Every request acts on behalf of your existing session — your cookies, your TLS, your JS context — exactly as if you'd clicked it in the browser yourself. Treat this as informal use of homes.com. Use at your own discretion.\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `homes_search_properties` | Search listings by free-text location (city/ZIP/neighborhood). Slugifies the input into homes.com's URL routing and parses the JSON-LD `CollectionPage.mainEntity.itemListElement[]`. Filters by `property_type`, `listing_type`, `sort`, and a `price_min`/`price_max` band. Returns address, price, beds/baths, sqft, primary photo, listing agent + brokerage; flags `truncated`/`total_estimated` past the ~40-listing SSR cap. |\n| `homes_get_by_address` | Resolve one US street address to its canonical homes.com property URL + opaque hash. Walks structured typeahead → slug → city/zip search-fallback with whole-token street + unit verification. Returns `matched_via`; degrades to `{ resolved: false }`. |\n| `homes_resolve_addresses` | Bulk `homes_get_by_address` (up to 100 addresses, input order preserved, per-row outcomes). Prefer for batches ≥ 3. |\n| `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, agent + brokerage, highlights, schools, HOA (raw + monthly), lot size (sqft + acres), parking, heating/cooling, MLS id/source, tax, days-on-market, price drops, `extracted_features`. Optional inline `price_history`/`tax_history`. |\n| `homes_get_property_photos` | Full photo gallery scraped from `<img>` tags on the detail page (JSON-LD only carries one image). Returns `{ url, position, alt? }` per photo, filtered to the homes.com CDN. |\n| `homes_bulk_get` | Fetch up to 200 properties' structured records in one call (per-row errors, input order preserved). |\n| `homes_compare_properties` | Side-by-side comparison of 2–8 properties with an aligned summary table. Per-target errors captured per-row. Concurrent fetches. |\n| `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. |\n| `homes_get_history` | Combined price + tax history in one fetch: `listing_events`, `ownership_events`, `lien_events`, normalized `events_normalized`, and `tax_records`. |\n| `homes_get_property_history` | *Deprecated* — price/ownership/lien timelines only. Prefer `homes_get_history`. |\n| `homes_get_tax_history` | *Deprecated* — year-by-year tax records only. Prefer `homes_get_history`. |\n| `homes_get_market_report` | Median / average / $-per-sqft for a market, derived from the `sold` search page's JSON-LD. |\n| `homes_get_saved_homes` | The signed-in user's saved (favorited) homes. Auth-gated. |\n| `homes_get_saved_searches` | The signed-in user's saved searches. Auth-gated. |\n| `homes_calculate_affordability` | Local affordability calculator — max purchase price from income + DTI + rates. No network. |\n| `homes_calculate_mortgage` | Local PITI calculator — principal+interest, taxes, insurance, HOA, PMI. No network. |\n| `homes_estimate_rent_vs_buy` | Local rent-vs-buy model — you supply `monthly_rent` (homes.com has no rental signal to impute it; see below). No network. |\n| `homes_healthcheck` | Round-trips `/robots.txt` through the fetchproxy bridge (the shared `registerBridgeHealthcheckTool` from `@chrischall/mcp-utils/fetchproxy`) and returns diagnostics: bridge role/port/version, the extension link state (`bridge.session_state`, `pending_pair_code`, `extension_connected`), a classified `error.kind` (`timeout` / `bridge_down` / `session_not_ready` / `protocol` / `unknown`), and a plain-English hint distinguishing \"bridge down\" from \"extension not connected / pair code pending\" from \"homes.com-side problem.\" |\n| `homes_get_session_context` / `homes_register_session` / `homes_set_active_session` | List / register / switch logical homes.com sessions. |\n\n### Known data gap: rental estimates\n\nhomes.com does NOT publish rental estimates anywhere on its consumer site — there's no `rent_zestimate` analogue, no \"estimated rent\" widget on property detail pages, and no comparable-rentals endpoint. The `homes_estimate_rent_vs_buy` tool exists for the math, but it requires the caller to pass `monthly_rent` directly (you can't fetch a rent estimate from homes.com to plug in).\n\nFor rental signals, use a sibling MCP: **`zillow_get_property`** carries `rent_zestimate` on detail records, and **`redfin_get_comparable_rentals`** returns rental comps by URL. See [issue #28](https://github.com/chrischall/homes-mcp/issues/28) for the feasibility investigation.\n\n## Acknowledgement of Terms\n\nBy using this MCP server, you acknowledge and agree to the following:\n\n**1. This server accesses your own homes.com session.** Every request is dispatched through your own browser tab via the fetchproxy extension — your cookies, your TLS, your session. It does not — and cannot — access anyone else's account.\n\n**2. [homes.com's Terms of Use](https://www.homes.com/about/terms-of-use) govern your use of this server**, just as they govern your direct use of homes.com. The terms prohibit automated crawling without written permission, and IDX listing data is licensed for personal, non-commercial use only. You are agreeing to those terms every time you invoke a tool in this server.\n\n**3. Personal, non-commercial use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with homes.com or CoStar Group. It is a personal automation tool that reads the same server-rendered HTML and Schema.org JSON-LD homes.com ships to your browser. Do not use it to bulk-extract listings, redistribute IDX data, train AI models, populate a competing real-estate product, or for any commercial purpose.\n\n**4. Stability is not guaranteed.** This server reads Schema.org JSON-LD (`<script type=\"application/ld+json\">`) and DOM-side `<img>` tags from SSR pages whose URL conventions (`/<city>-<state>/`, `/property/<slug>/<id>/`) may change without notice. It may break. It may stop working. That's by design — the surface is not theirs to maintain on our behalf.\n\n**5. You accept full responsibility** for any consequences of using this server in connection with your homes.com access — rate limiting, account suspension, IP blocks, AWS WAF challenges, or any enforcement action homes.com takes. If homes.com objects to your use, stop using this server.\n\nThis section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede homes.com's actual ToU.\n\n## Install\n\n### Option A — npx (after first publish)\n\nAdd to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"homes\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"homes-mcp\"]\n    }\n  }\n}\n```\n\n### Option B — from source\n\n```bash\ngit clone https://github.com/chrischall/homes-mcp\ncd homes-mcp\nnpm install\nnpm run build\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"homes\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/homes-mcp/dist/bundle.js\"]\n    }\n  }\n}\n```\n\n### One-time browser setup\n\nhomes-mcp talks to your browser through the [fetchproxy](https://github.com/chrischall/fetchproxy) extension, which is shared across every fetchproxy-based MCP (zillow-mcp, opentable-mcp, resy-mcp, …). It lives in its own repo and is installed separately — it is **not** bundled here. Follow the install instructions at [github.com/chrischall/fetchproxy](https://github.com/chrischall/fetchproxy), then load the built extension in Chrome via `chrome://extensions` → toggle Developer mode → Load unpacked.\n\nOpen homes.com and sign in. That's all the auth this server needs.\n\n## How it works\n\n```\n┌────────────────┐  stdio   ┌──────────────────┐   WS   ┌──────────────────┐    fetch()    ┌─────────────┐\n│ MCP client     │◀────────▶│  dist/bundle.js  │◀──────▶│  fetchproxy      │◀────────────▶│ homes.com  │\n│ (Claude, etc.) │          │  (Homes MCP)    │ :37149 │  extension       │   (real TLS, │ (your tab)  │\n└────────────────┘          └──────────────────┘        │  (separate)      │   cookies)    └─────────────┘\n```\n\nThe MCP server runs in Node, but every HTTP call to homes.com is dispatched into your live browser tab through the fetchproxy extension. Each request rides your existing session — TLS fingerprint, cookies, and JS execution context all match the page that's already on screen. No headless browser stand-in, no separate identity, no third-party proxy: just your real browser, acting on its own behalf, with the MCP server picking what to ask for.\n\nhomes.com's pages are SSR React with no public JSON API — every tool extracts data from the Schema.org JSON-LD block embedded in each page (`<script type=\"application/ld+json\">`). Search pages put listings in `CollectionPage.mainEntity.itemListElement[]`; detail pages emit a `RealEstateListing` graph node with `mainEntity` (address, size, geo) and `offers.offeredBy[]` (listing agent). Photos are scraped from the DOM since the JSON-LD only carries one primary image. The client wraps that into the tool surface so callers never have to parse HTML themselves.\n\n## Commands\n\n```bash\nnpm test               # tsc typecheck + vitest, mocked transport, no network\nnpm run test:watch\nnpm run test:coverage\nnpm run build          # tsc --noEmit + esbuild bundle → dist/bundle.js\nnpm run dev            # node dist/bundle.js (after build)\n```\n\n## License\n\nMIT\n",
  "bytes": 10295,
  "sha": "852184959ad66c794579f82f5ab6d1e8f431ef086c35431cfd1655ae8c3aaea9",
  "repo_slug": "chrischall/homes-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_chrischall_homes_mcp_22b9ec97/readme"
}