zillow-mcp

An unofficial, experimental MCP (Model Context Protocol) server that lets a model search Zillow listings.

Unofficial and experimental. Not made by, affiliated with, or endorsed by Zillow in any way. It works by reading Zillow's own public search-result pages, not a real API, so it can stop working at any time. See Known limitations before you rely on it for anything.

No API key -- Zillow does not offer a public listings API. This works by fetching Zillow's own search-results pages the way a browser would, and reading the listing data out of the HTML. That is also exactly why it can break: see Known limitations before you rely on it for anything.

"3+ bed, 2+ bath rentals in Austin, TX, newest first"

  search_homes(location="Austin, TX", status="rent",
               min_beds=3, min_baths=2, sort="newest")

  -> resolved_location: "Austin TX"
     41 listings
     [{ address: "100 Example St, Austin, TX 78701", price: 2450,
        beds: 3, baths: 2, sqft: 1650, zpid: "10000001",
        url: "https://www.zillow.com/homedetails/...", days_on_zillow: 4 }, ...]

Why this exists

Zillow has no public API for listing search. What it has is a server-rendered search page: type a location into zillow.com, and the HTML that comes back has the full result set embedded as JSON, no follow-up API call needed. This project fetches that page directly with a plain HTTP request and reads the JSON back out.

That is the entire mechanism, and it is worth being direct about what it is not: it is not an API integration, it is not guaranteed to keep working, and it is not affiliated with Zillow in any way. It is a best-effort, reverse-engineered method, and the design here is built around being honest about that rather than hiding it:

One tool. search_homes. No location-geocoding tool bolted on the front, no separate rent/sale/sold tools -- location is plain text and status is a plain parameter, resolved internally.

Accept what a model actually has. location takes a city and state ("Austin, TX"), a ZIP code ("78704"), or a neighborhood -- whatever text a model would naturally reach for. No pre-resolved coordinates, no Zillow region ID.

Never return a bot-check page as if it were listings. This is the one that matters most for a scraper. Every failure mode is caught explicitly and never silently parsed as a normal result:

• Zillow's bot-check challenge page (PerimeterX) -- detected by signature, not treated as an empty result set.

• A location Zillow can't place, which -- confirmed by testing -- doesn't error, it silently falls back to some default region and returns a normal-looking page full of real listings for the wrong place. Every result is checked against what was actually asked for before being returned; see The two problems worth reading the code for.

• A location specific enough to redirect to one property's page instead of a search-results page.

Errors are instructions. Every failure says what to do next: retry in a bit, use a more specific location, widen the filters. None of them just say "failed."

Related MCP server: Zillow56 MCP Server

Install

pip install -e .

Claude Code:

claude mcp add zillow -- zillow-mcp

Claude Desktop -- in claude_desktop_config.json:

{
  "mcpServers": {
    "zillow": {
      "command": "zillow-mcp"
    }
  }
}

No environment variables, no API key -- there's nothing to configure.

Tool

Parameters: location (required -- city/state, ZIP, or neighborhood), status (rent / sale / sold, default rent), min_price, max_price, min_beds, max_beds, min_baths, max_baths, sort (relevant / newest / price_asc / price_desc / beds / baths / sqft / lot_size), page.

Search only. There is no single-property-detail tool in v1 -- if a location is specific enough that Zillow resolves it to one address, the tool refuses with an explanation rather than guessing at what you wanted.

The two problems worth reading the code for

A silent wrong location is worse than an error

Feed Zillow's search endpoint a location it doesn't recognize and it does not return an error page. It falls back to some default region -- during testing, that was consistently Saint George, UT, for a machine whose actual location is nowhere nearby -- and serves back a completely normal-looking results page, 41 real listings, no error text anywhere. A naive integration would return those listings as if they answered the question asked.

zillow_mcp/location.py's resolution_matches exists entirely to catch this: after the page comes back, the region Zillow actually resolved (from the page's own regionState) is checked against what was typed, using token overlap for city/state text and substring matching for ZIP codes. A mismatch raises an error naming both the requested location and what Zillow actually returned, rather than handing back results for the wrong city with a straight face.

Telling a bot-check page from a real one, cheaply

Zillow runs bot detection (PerimeterX) in front of these pages. A plain httpx GET has none of the signals a browser has, so it gets challenged sometimes -- during development, requests moved from succeeding consistently to being blocked consistently within the same short testing session, which suggests the block is tied to request-pattern/session reputation, not just IP identity. zillow_mcp/client.py checks every response for PerimeterX's signature text (px-captcha, perimeterx, "access to this page has been denied") and for a 403/429 status, regardless of whether the HTTP status looks successful -- a block can come back as an ordinary 200 with a challenge document as the body. A match raises an error that says plainly that this is a bot check, that this method is unofficial and expected to fail sometimes, and suggests retrying later or spacing out requests -- never an attempt to parse the challenge page as if it contained listings.

What actually works right now (tested live, September 2026)

• Plain-text location works with no geocoding step. A bare ZIP code or a city-state slug placed directly in the URL path (/homes/for_rent/austin-tx/, /homes/for_rent/78704/) resolves the region server-side. No bounding-box math, no separate geocoding request -- confirmed against live Zillow search URLs.

• When a request gets through, the data is real and complete. Address, price, beds, baths, sqft, zpid, listing URL, days on Zillow, lat/lng -- all present in the embedded __NEXT_DATA__ JSON on a successful fetch.

• Bot-blocking is real and inconsistent. In testing, the first several requests in a session succeeded cleanly (HTTP 200, full listing data, correct region). After a short burst of requests, every subsequent request in that session was blocked with a PerimeterX challenge page, even for URLs that had succeeded minutes earlier. A single request after a pause succeeded again. Practical read: this works well for occasional, spaced-out queries and is not reliable for back-to-back or high-volume use. There is no retry/backoff logic built in on purpose -- see below.

Known limitations

• Unofficial and reverse-engineered. This is not a Zillow product, has no affiliation with Zillow, and uses no official API. It works by reading Zillow's own public search-results HTML.

• Can break at any time. Zillow can change its page structure, its embedded-JSON format, or tighten its bot detection with no notice, and any of those can silently stop this from working. zillow_mcp/parser.py documents exactly where in the JSON it expects the listings to be, so a break is a small, findable diff rather than a mystery.

• Gets blocked, and that's treated as normal, not a bug. No headless browser, no proxy rotation, no CAPTCHA solving -- this is a plain HTTP request on purpose (see Constraints below). When Zillow's bot detection catches it, the tool says so clearly instead of failing silently or returning something that looks like real data.

• Not for high-volume use. No caching, no request queue, no retry logic. Space requests out. Hammering it will get the requesting IP blocked faster, not return more data.

• Data may be stale or inaccurate. This reads whatever Zillow's page currently shows; it is not a live feed and carries no guarantee of freshness or correctness. Verify anything that matters on zillow.com directly.

• Location resolution is a heuristic, not a geocoder. The wrong-location check (resolution_matches) catches clearly mismatched regions using word overlap, not authoritative geocoding. It can, in principle, be fooled by a real-but-coincidental word match, or reject a legitimate location it doesn't recognize the phrasing of.

• No single-property lookup. Search only, by design (see Scope above). An address-like location fails with an explanation instead of returning that one property.

Why a plain HTTP request

A headless browser or a paid scraping/proxy service would almost certainly get through more often. Both were deliberately left out of v1: a headless browser is a much heavier dependency and runtime cost for a tool meant to be simple to install, and a paid proxy service means a second thing to sign up for and pay for just to try this out. The trade-off is accepted on purpose -- this fails openly and instructively when blocked rather than pretending to be more reliable than it is.

Tests

python3 tests/test_url.py
python3 tests/test_parser.py
python3 tests/test_protocol.py

test_url.py and test_parser.py run offline -- no network, nothing that can break because Zillow changed something or is blocking requests right now. test_parser.py runs against a saved local HTML fixture (tests/fixtures/search_results.html) rather than a live page; that fixture is a hand-built stand-in matching the real __NEXT_DATA__ shape confirmed by inspecting live Zillow pages, not a captured copy of an actual page, so no real scraped listing data ships in this repo. test_protocol.py launches the server as a subprocess and talks to it over the real MCP stdio protocol -- the only live-feeling part of that test is a deliberately bad parameter, which fails validation before any network request, so it stays deterministic.

Evals

python3 evals/run_eval.py

Runs search_homes against a handful of real Zillow queries and reports each as succeeded, cleanly blocked, or -- the only real failure category -- unexpected (a crash, malformed output, or a wrong-location bug slipping through). A blocked result is not a failing eval; a silent wrong answer is. It also runs one negative case (a specific street address) to confirm the single-property-page guard rail actually fires instead of quietly returning that one home.

Not affiliated with Zillow

Zillow is a trademark of Zillow, Inc. This project is not produced, endorsed, or supported by Zillow in any way.

License

MIT