zillow-mcp

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

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.

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.

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"`.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.