# zillow-mcp [Health: Active]

**Category:** 🏠 Real Estate  
**Repository:** https://github.com/chrischall/zillow-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 2230  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/zillow-mcp

## Description
Zillow real-estate for Claude — search, property details, Zestimates, saved searches & homes

## Tools
Capabilities this server exposes over MCP:

- **zillow_search_properties** — Search Zillow listings by location (city, ZIP, neighborhood, or address) and optional filters (status, price band, beds/baths minimums, home types). Returns matching properties with price, beds/baths, sqft, Zestimate, status, image, and homedetails URL. Works with city/ZIP-level queries (filtered against your criteria) AND with full-address or street-only queries (returns the listings Zillow resolves to directly — filters are not applied in this single-round-trip path; use zillow_get_by_address for the cleanest one-shot address → zpid lookup). Throws LocationNotResolved if Zillow can't pin either a region or matching listings for the input (instead of silently falling back to your default search region). Heads up: Zillow renders ~40 listings per page server-side; this tool auto-paginates by default when `limit` exceeds that, walking subsequent pages and concatenating results (set `auto_paginate: false` to opt out and get the single-page response). For dense markets, price-band the search to enumerate fully. Does NOT return Zestimate history — use zillow_get_zestimate_history for that. Read-only; safe to call repeatedly.
- **zillow_sweep_area** — Enumerate EVERY Zillow listing matching the filters inside a location (resolved like zillow_search_properties) or an explicit bounding box, without silent truncation. Splits the area into map tiles and recursively quarters any tile whose Zillow-reported total exceeds what one query can return, dedupes by zpid and re-applies the numeric filters (drift guard). Returns a completeness summary (requests, tiles, unique listings, tiles still truncated at max depth, drift warnings such as Zillow ignoring the price filter or the viewport) plus the listings, or writes the listings to `output_path` as JSON for large areas (inside the output directory: ZILLOW_OUTPUT_DIR, default ~/Downloads/zillow-mcp). Sequential requests with a delay, paced by the same per-host requests-per-minute throttle as `zillow_bulk_get`; if Zillow's bot-wall blocks a request the sweep stops and returns `{ blocked: true, retry_after_s }` with what it had. Read-only against Zillow; the only write is the optional local output file.
- **zillow_get_property** — Fetch a property's full Zillow record by zpid (numeric Zillow Property ID, e.g. 12345) or by homedetails URL. Returns address (Zillow's slugged form), mls_street_address (canonical MLS form — prefer this when it disagrees), neighborhood, price, Zestimate, rent Zestimate, beds/baths, square footage, lot_size (sq ft) plus the derived lot_size_acres (round(lot_size / 43560, 2); both null — never 0 — for condos and listings with no lot), year built, schools, and an `extracted_features` block (lake_front, hot_tub, basement, furnished, dock, community) keyword-parsed from the description. Also returns `zest_vs_list_pct` — the list-vs-Zestimate spread, `(price − zestimate) / zestimate × 100` rounded to 1 decimal: POSITIVE means listed ABOVE the Zestimate, negative below (null when either input is missing). The raw `description` is omitted by default — pass `include_description: true` to keep it; in most cases the extracted features cover what callers need. Price-history and tax-history are also opt-in (`include_price_history: true` / `include_tax_history: true`) — bundle them in to skip a separate call. Provide exactly one of zpid or url. Read-only; safe to call repeatedly.
- **zillow_get_zestimate_history** — Historical Zestimate values for a property by zpid or homedetails URL. Returns a time series of {date, value, rent?} entries (rent included when Zillow has a rent Zestimate for the property). Note: zillow_get_property returns only the *current* Zestimate as a scalar — call this tool when you need the trend. For some listings (commonly non-Showcase) Zillow renders the trend client-side and omits it from the server-rendered page; then `points` is empty and an explanatory `note` is returned — distinct from a genuine no-history. Read-only; safe to call repeatedly.
- **zillow_get_saved_searches** — The signed-in user's saved searches on zillow.com (name, filters, new-listing count, notification frequency). Requires the user to be signed in at zillow.com in the bridged browser tab — throws SessionNotAuthenticatedError otherwise. An optional `session_id` (from `zillow_register_session`) is checked against the session registry — an unknown id errors — but it is a label only: the request always goes through whichever browser tab the extension is signed into. Read-only; safe to call repeatedly.
- **zillow_get_saved_homes** — The signed-in user's saved (favorited) homes on zillow.com, flattened across all of the user's collections. Returns address, price, Zestimate, status, and when each home was saved. An optional `session_id` (from `zillow_register_session`) is checked against the session registry — an unknown id errors — but it is a label only: the request always goes through whichever browser tab the extension is signed into. Requires the user to be signed in. Read-only; safe to call repeatedly.
- **zillow_get_market_report** — Market report for a Zillow region: median sale/list prices, days on market, for-sale inventory, new listings, Zillow Home Value Index (ZHVI), and year-over-year ZHVI change. Provide either a `region_path` (e.g. "/home-values/6181/brooklyn-ny/") or a full Zillow home-values URL. Read-only; safe to call repeatedly.
- **zillow_calculate_mortgage** — Local-only mortgage payment calculator. Returns a full PITI breakdown (principal + interest, property tax, insurance, HOA, PMI) and total interest over the life of the loan. No network call — fully deterministic, safe to use for scenario comparison without burning a fetch. Provide either `down_payment` OR `down_payment_percent`; defaults to 20%. Property tax can be given as `property_tax_annual` or `property_tax_rate` (% of home price). PMI applies automatically when LTV > 80% and `pmi_rate` is provided.
- **zillow_get_price_history** — Listing-price events for a property — listings, price changes, pending, sold, etc. — by zpid or homedetails URL. Returns two parallel arrays: `events` (raw Zillow shape with `event` strings and MLS attribution) and `events_normalized` (cross-MCP shared shape with a fixed `type` enum: Listed/PriceChange/Pending/Contingent/Sold/Withdrawn/Relisted/Delisted). The normalized form lets callers merge histories across real-estate MCPs without re-implementing taxonomy. Sourced from the same homedetails page as zillow_get_property. For some listings (commonly non-Showcase) Zillow omits the history from the server-rendered page; then `events` is empty and an explanatory `note` is returned — distinct from a genuine no-history.
- **zillow_get_tax_history** — Year-by-year property-tax record for a property: tax paid, assessed value, and the year-over-year change rates. Sourced from the homedetails page. Useful for spotting reassessment jumps or comparing tax burdens across properties. For some listings (commonly non-Showcase) Zillow omits the history from the server-rendered page; then `events` is empty and an explanatory `note` is returned — distinct from a genuine no-history.
- **zillow_compare_properties** — Side-by-side analysis of 2-25 Zillow properties. **If you just want N property records, use `zillow_bulk_get` instead** — compare is for genuine side-by-side (its pivoted summary table is the value-add); bulk_get is the fetch-many endpoint and accepts up to 200 ids. (Issue #79 raised this cap from 8 to 25 — a 19-listing analysis now fits in one call instead of three.) Provide an array of zpids (or homedetails URLs). Returns the full per-property record per row (with `extracted_features` populated). Pass `include_summary: true` for an extra pivoted summary table (one row per field) — defaults off because `results[].property.*` already carries everything. The raw `description` is omitted from each row by default — pass `include_description: true` to keep it. Errors for individual properties are captured per-row — one bad zpid won't fail the whole call. Calls fan out concurrently (capped at 6 in flight, per issue #78, with retry-once-on-timeout per sub-request to absorb transient SW evictions), paced by the same throttle as `zillow_bulk_get`; a bot-wall block is retried with backoff and, if it persists, reported as `error_kind: "bot_challenge"` (distinct from a missing listing) with `{ blocked, retry_after_s }` on the envelope. The call is bounded by an overall deadline — unsettled rows come back as `error_kind: "pending"`.
- **zillow_calculate_affordability** — Solve for the maximum home price you can afford under the standard 28/36 DTI rule. Inputs: monthly income, recurring monthly debts (car loans, student loans, etc.), down payment, interest rate, and optional property-tax rate / insurance / HOA / loan term. Output: max home price, the binding constraint (front-end vs back-end), and the full PITI breakdown at that price. Same math across the realty MCP cohort (@chrischall/realty-core). No network — pure local math.
- **zillow_estimate_rent_vs_buy** — Project the cumulative cost of buying a home versus renting a comparable place over N years. Accounts for down payment, closing costs, monthly PITI, maintenance (~1%/yr default), property appreciation (~3%/yr default), rent growth (~3%/yr default), and the opportunity cost of the down payment (renter invests it at the investment_return_rate, default 6%/yr). Mortgage P&I stops once the loan is paid off, so horizons longer than the loan term are handled. horizon_years and loan_term_years are capped at 50. Returns the year-by-year cumulative costs, the break-even year, and the net difference at the horizon. No network — pure local math.
- **zillow_get_property_photos** — The full photo gallery for a Zillow property — every image embedded in the homedetails page. Each entry returns the canonical hero URL plus the widest jpeg + webp variants and caption when present. Provide exactly one of `zpid` or `url`. Set `include_sources: true` to also include the full multi-width source lists (warning: a 50+ photo property can exceed the per-call token budget). Returns `{ zpid, count, photos, street_view_url?, high_res_url? }`. Read-only; safe to call repeatedly.
- **zillow_healthcheck** — Round-trips a small public www.zillow.com URL (/robots.txt) through ContextMint Bridge (your signed-in browser tab) and returns diagnostics: the bridge's role (host/peer/null), port, version, the extension link (linked / pair pending / not attached / never answered), the elapsed round-trip time, and a plain-English hint distinguishing 'bridge never came up' from 'extension not connected' from 'this browser can't serve a capability' from 'real www.zillow.com-side problem'. Read-only, no auth required. Call this when a real tool fails and you want to know which hop broke.
- **zillow_get_by_address** — Resolve a free-text address (with optional city/state/zip) to its Zillow canonical homedetails URL and zpid. IMPORTANT: for rural / mountain-MLS / locality-mismatched addresses (the search-fallback rung is often the ONLY rung that hits), ALWAYS pass `price_min` and `price_max` if you have any sense of the property's price band — without them the city/state search can't disambiguate and the call returns `{ resolved: false }`. The price params are not optional niceties; they are frequently load-bearing. Tries up to 5 rungs: (1) direct resolver hit, (2) autocomplete typeahead — Zillow's own canonical address suggestions, whole-token street-matched then resolved to a zpid (high recall), (3) bidirectional street-token swap ("Rd" <-> "Road", "Hts" <-> "Heights", "Bluebird" <-> "Blue Bird"), (4) locality remap — city-drop + locality-alias substitution when the caller-supplied city fails (real-world cases: Lake Lure <-> Rutherfordton, Beech/Sugar Mountain <-> Banner Elk), (5) city/state search fallback bounded by the price band. Returns `via: "direct" | "autocomplete" | "suffix_expansion" | "locality_remap" | "search_fallback"` so the caller knows how the match was made; when the locality remap fires, `queried_city` (what you sent) and `resolved_city` (what Zillow returned) are both set so the caller can see the substitution. Degrades to `{ resolved: false }` when ALL rungs miss — does not throw. Read-only, no auth required.
- **zillow_bulk_get** — Fetch up to 200 Zillow property records in a single call — the "give me everything for these N saved homes" endpoint. Returns one structured row per input id (no pivoted side-by-side summary table — for 2-25 listings with a comparison summary use `zillow_compare_properties`). Each row is either `{ zpid, status: "ok", property }` on success or `{ zpid, status, error_kind, retryable, error }` on failure (`status` = `error_kind`) — one bad zpid never fails the whole call. Calls fan out concurrently against `/homedetails/<zpid>_zpid/` (capped at 6 in flight, per issue #78, with retry-once-on-timeout per sub-request to absorb transient SW evictions). Big lists fan out bounded to 6 in flight and paced by a per-host requests-per-minute throttle (burst 20) so the batch doesn't trip Zillow's PerimeterX bot-wall (issue #90). If the bot-wall is hit, the blocked sub-requests are retried with exponential backoff; anything still blocked is reported with `error_kind: "bot_challenge"` (distinct from a missing listing) and the response carries a `{ blocked, retry_after_s }` envelope so you can finish the rest in a second pass. The whole call is bounded by an overall hard deadline (issue #98): a single slow/hung row never wedges the server — when the deadline is reached any row that has not yet settled is returned with `error_kind: "pending"` and the response carries a `{ pending }` count so you can re-run just those ids. The envelope also reports `count` / `ok` / `errored`.
- **zillow_resolve_addresses** — Resolve up to 100 free-text or structured addresses to Zillow zpids + canonical URLs in one call. Each row may be a bare string or `{address, city?, state?, zip?, price_hint?}`. IMPORTANT: `price_hint` (USD) is frequently load-bearing — for rural / mountain-MLS / locality-mismatched rows the search-fallback rung is often the ONLY rung that hits, and without a price band it cannot disambiguate. The resolver derives a ±0.5% band from the hint. Always pass `price_hint` for any row where you have a sense of the price. Runs the same 5-rung resolver as `zillow_get_by_address` (direct → autocomplete-typeahead → suffix-expansion → locality-remap → search-fallback) — bulk and single walk the same ladder via the shared resolver, so they match the same partition for the same inputs. Locality-remap rung handles real-world mountain-MLS cases (Lake Lure <-> Rutherfordton, Beech/Sugar Mountain <-> Banner Elk) where Zillow indexes the parent locality; when it fires, `queried_city` (what you sent) and `resolved_city` (what Zillow returned) are both set so the caller can see the substitution. Concurrent fan-out — a 60-address batch returns in roughly one round trip instead of 60. Per-row error capture so one bad address never fails the batch. `confidence` is `"exact"` for direct hits, `"autocomplete"` / `"suffix_expansion"` / `"locality_remap"` / `"search_fallback"` for retries, `"none"` when all rungs missed. The whole call is bounded by an overall hard deadline (issue #98), like `zillow_bulk_get`: a single slow/hung row never wedges the server — when the deadline is reached any unsettled row is returned with `error_kind: "pending"` (distinct from a real miss) and the response carries a `pending` count so you can re-run just those addresses. Every lookup is paced by the same per-host requests-per-minute throttle as `zillow_bulk_get` so a big batch does not trip Zillow's PerimeterX bot-wall. If the wall is hit, the remaining rows stop querying Zillow and come back with `error_kind: "bot_challenge"` (never a plain miss), and the response carries a `{ blocked, retry_after_s }` envelope so you can re-run them later. Other failed rows carry `error_kind` `timeout` / `bridge_down` / `protocol` / `other`. Read-only, no auth required.
- **zillow_register_session** — Record (or refresh) which Zillow account the signed-in session belongs to, keyed by `account_identity`. Re-registering the same identity updates the existing entry. Returns a `session_id`; pass `mark_active: true` to mark it as the current account in the same call. The registry is a label only: it does not change which Zillow account requests use. Every zillow tool call goes through whichever browser tab the ContextMint Bridge extension is signed into; to read a different account, sign that tab into it.
- **zillow_set_active_session** — Mark a previously registered `session_id` as the current account label, for your own bookkeeping across a conversation. The registry is a label only: it does not change which Zillow account requests use. Every zillow tool call goes through whichever browser tab the ContextMint Bridge extension is signed into; to read a different account, sign that tab into it.
- **zillow_get_session_context** — List every registered account label plus the current `active_session_id`. When none are registered, `sessions` is empty and `active_session_id` is null. The registry is a label only: it does not change which Zillow account requests use. Every zillow tool call goes through whichever browser tab the ContextMint Bridge extension is signed into; to read a different account, sign that tab into it.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "zillow-mcp": {
    "command": "npx",
    "args": ["-y","zillow-mcp"]
  }
}
```

## Documentation

## What zillow-mcp does

zillow-mcp exposes Zillow real-estate workflows as MCP tools. It can search by city, ZIP code, neighborhood, or address; resolve free-text addresses to Zillow property IDs and canonical URLs; retrieve detailed property records; and collect photos, Zestimate history, listing-price events, and tax history. Batch tools support resolving up to 100 addresses or fetching up to 200 property records, while comparison supports side-by-side analysis of 2–25 properties.

The server also covers account-scoped Zillow data. When the connected browser is signed in, agents can read saved searches and saved homes. Regional market reports include measures such as median prices, days on market, inventory, new listings, ZHVI, and year-over-year ZHVI change.

Three local calculators avoid Zillow requests: mortgage payments with a PITI breakdown, maximum purchase price under the 28/36 debt-to-income rule, and multi-year rent-versus-buy projections.

## How it works

Requests to Zillow are routed through the ContextMint Bridge browser extension and the browser tab that is signed in to Zillow. The server uses that tab's session, cookies, TLS context, and JavaScript environment. The session registry can label accounts and identify an active label, but it does not switch the account used by requests; changing accounts requires signing the bridged browser tab into the desired account.

Searches can automatically paginate beyond Zillow's roughly 40-listing server-rendered page size. For exhaustive area enumeration, `zillow_sweep_area` divides a location or bounding box into map tiles, recursively subdivides truncated tiles, deduplicates by zpid, and reports completeness information. Batch retrieval and address resolution use bounded concurrency, throttling, retries, deadlines, and per-row error reporting. Zillow bot-wall responses are surfaced separately from missing listings.

## Setup and configuration

The server can be run with `npx -y zillow-mcp`, or built from source with `npm install`, `npm run build`, and a Node command pointing to `dist/bundle.js`. Add the command to an MCP client's server configuration.

Install the ContextMint Bridge extension separately and load its unpacked Chrome build through `chrome://extensions` with Developer Mode enabled. Safari support is not available in the described setup. A browser tab must be available to carry Zillow requests; saved searches and saved homes additionally require that tab to be signed in.

Large sweep results can be written as JSON using `output_path`. The output directory is controlled by `ZILLOW_OUTPUT_DIR` and defaults to `~/Downloads/zillow-mcp`.

## Tools and capabilities

- Search and sweep Zillow listings with location, status, price, bed, bath, home-type, map-bound, and pagination controls.
- Resolve one or many addresses, including Zillow canonical URLs, zpids, confidence, and locality-remapping details.
- Retrieve property records, photo galleries, current and historical Zestimate data, listing events, tax records, and optional descriptions.
- Fetch saved searches, saved homes, market reports, and browser-bridge diagnostics.
- Fetch property records in batches or compare multiple properties with partial per-row failures.
- Calculate mortgage payments, affordability limits, and rent-versus-buy outcomes locally.

## Limitations and notes

Zillow does not publish a public consumer API for this use case. The server relies on private web-app endpoints and rendered Zillow pages, which Zillow can change without notice. Zillow's terms broadly prohibit automated access without permission, and the project is intended for personal, non-commercial use rather than bulk extraction, model training, or a competing real-estate product.

Requests may encounter rate limits, bot challenges, CAPTCHA walls, account warnings, IP blocks, or browser-bridge failures. The healthcheck tool helps distinguish bridge, extension, browser-capability, and Zillow-side problems. Some price, tax, or Zestimate histories are absent from Zillow's server-rendered page; the tools return an explanatory note in those cases. Address resolution may require a price hint for rural or locality-mismatched properties, and `zpid` inputs must be numeric IDs rather than `_zpid` strings or URLs. Use the dedicated `url` fields for homedetails URLs.

_Full upstream README: https://allmcps.com/mcp/zillow-mcp/readme_

