# zillow-mcp

[![CI](https://github.com/chrischall/zillow-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/zillow-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/zillow-mcp)](https://www.npmjs.com/package/zillow-mcp)
[![license](https://img.shields.io/npm/l/zillow-mcp)](LICENSE)

Zillow real-estate access as an MCP server for Claude — search listings, fetch property details, Zestimate history, your saved searches & homes, and market reports via natural language.

> ⚠️ Zillow does not publish a public consumer API. The official [Bridge API](https://www.bridgeinteractive.com/developers/bridge-api/) is gated to MLS partners. This server uses the same private endpoints the zillow.com web app uses, routed through your own signed-in browser tab via the [ContextMint Bridge](https://github.com/nullnet-app/contextmint-bridge) browser 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 Zillow's website. Use at your own discretion.

## Why this exists

The four existing Zillow MCPs all sit on one of two foundations:

- The **Bridge API** — requires MLS membership, IDX vendor relationship, or "approved technology partnership" (10+ business-day approval). Consumers can't get in.
- A **paid scraper** (RapidAPI, Apify) — adds a third party to the trust path and rate-limits.

None of them can see what *you* have saved, favorited, or recently viewed — because both Bridge and third-party scrapers are out-of-session. zillow-mcp uses your already-signed-in zillow.com tab.

## Tools

| Tool | Purpose | Auth-scoped |
| --- | --- | :---: |
| `zillow_search_properties` | Search listings by location, status, price band, beds/baths, home type. Optional `map_bounds` viewport; `include_meta` reports Zillow's own total vs fetched, so truncation is visible | |
| `zillow_sweep_area` | Exhaustive enumeration of an area: recursive map tiling until no tile is truncated, deduped, with a completeness summary and drift warnings; optional JSON output file | |
| `zillow_get_property` | Full record for a zpid (price, Zestimate, beds, schools, neighborhood, price history) | |
| `zillow_get_by_address` | Resolve a free-text address (with optional city/state/zip) to its Zillow zpid + canonical URL | |
| `zillow_resolve_addresses` | Batch-resolve many free-text addresses (or structured rows) to zpids + canonical URLs | |
| `zillow_bulk_get` | Fetch full records for many zpids/URLs at once, with partial-result + bot-wall handling | |
| `zillow_get_property_photos` | Full photo gallery for a property — every image embedded in the homedetails page with multi-width jpeg + webp variants and captions | |
| `zillow_get_zestimate_history` | Time series of Zestimate values (and rent Zestimate where available) | |
| `zillow_get_price_history` | Listing history (Listed/Sold/Pending/etc.) with price + days on market | |
| `zillow_get_tax_history` | Annual tax-roll history — taxes paid and assessed value year-over-year | |
| `zillow_compare_properties` | Side-by-side comparison of up to 12 properties, with an aligned summary table | |
| `zillow_calculate_affordability` | Local affordability calculator — max purchase price from income/DTI/rates | |
| `zillow_estimate_rent_vs_buy` | Local rent-vs-buy break-even with appreciation + opportunity cost | |
| `zillow_get_saved_searches` | Your saved searches with new-listing counts and notification frequency | ✓ |
| `zillow_get_saved_homes` | Your favorited homes with current price + Zestimate + primary photo | ✓ |
| `zillow_get_market_report` | Median sale/list/rent, days on market, inventory, ZHVI for a region | |
| `zillow_calculate_mortgage` | Local PITI calculator — principal+interest, taxes, insurance, HOA, PMI (no network) | |
| `zillow_healthcheck` | Round-trip a public Zillow URL through the bridge to localize bridge/extension/Zillow-side failures | |
| `zillow_register_session` | Record which Zillow account the signed-in tab belongs to, in the local session registry (a label only) | |
| `zillow_set_active_session` | Mark a registered session as the current account label — does not change which account requests use (every call goes through the signed-in browser tab) | |
| `zillow_get_session_context` | Inspect the active session + the registered-session list | |

### Input and output contract

Changes to tool inputs and outputs, so you can adjust any scripts or prompts that call these tools:

- **`zillow_compare_properties` reports bot-wall rows like `zillow_bulk_get` does.** A row that Zillow keeps blocking with a captcha now comes back as `error_kind: "bot_challenge"` instead of a generic error kind, so you can tell it apart from a missing listing. The response can also include `blocked` (how many rows stayed blocked), `retry_after_s` (how many seconds to wait before retrying just those rows) and `pending` (how many rows did not finish before the overall deadline; those rows have `error_kind: "pending"`).

- **A zpid must be a number.** Every tool that takes a `zpid` (`zillow_get_property`, `zillow_bulk_get`, `zillow_compare_properties`, `zillow_get_property_photos`, `zillow_get_zestimate_history`, `zillow_get_price_history`, `zillow_get_tax_history`) accepts a positive whole number, or a string of digits only such as `"12345"`. Any other string, such as `"12345_zpid"` or a URL, is now rejected as invalid input. Pass a homedetails URL in the `url` or `urls` field instead.

- **Pass `zpids` or `urls`, not both.** `zillow_bulk_get` and `zillow_compare_properties` now return an error when a call includes both lists. Before, the `urls` list was silently ignored. To fetch both kinds, make two calls.

## Acknowledgement of Terms

By using this MCP server, you acknowledge and agree to the following:

**1. This server accesses your own Zillow session.** Every request is dispatched through your own browser tab (logged in or not) via the ContextMint Bridge extension. It does not — and cannot — access anyone else's account.

**2. [Zillow's Terms of Use](https://www.zillow.com/z/corp/terms/) govern your use of this server**, just as they govern your direct use of zillow.com. The clauses most relevant here:

> You may not use any robot, spider, scraper or other automated means to access the Services for any purpose without our express written permission… nor may you conduct automated queries (including screen and database scraping, spiders, robots, crawlers, bypassing CAPTCHAs or similar precautions).

You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. Zillow's terms broadly prohibit automated access without written permission; this is an unofficial tool and Zillow has not granted it permission.

**3. Personal, non-commercial use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with Zillow Group. It is a personal automation tool that drives the same Zillow website you would drive by hand — one search at a time, your own saved homes, your own market reports. Do not use it to bulk-extract listings, train models, populate a competing real-estate product, or for any commercial purpose.

**4. Stability is not guaranteed.** This server reads private internal endpoints (`/async-create-search-page-state/`, `__NEXT_DATA__` blobs, `/myzillow/...`) that Zillow 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.

**5. You accept full responsibility** for any consequences of using this server in connection with your Zillow access — rate limiting, account warnings, suspension, IP blocks, captcha walls, or any enforcement action Zillow Group takes. If Zillow objects to your use, stop using this server.

This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Zillow's actual ToS.

## Install

### Option A — npx (after publishing)

Add to `.mcp.json`:

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

### Option B — from source

```bash
git clone https://github.com/chrischall/zillow-mcp
cd zillow-mcp
npm install
npm run build
```

```json
{
  "mcpServers": {
    "zillow": {
      "command": "node",
      "args": ["/path/to/zillow-mcp/dist/bundle.js"]
    }
  }
}
```

### One-time browser setup

zillow-mcp talks to your browser through the **ContextMint Bridge** extension, which is shared across every fetchproxy-based MCP (resy-mcp, opentable-mcp, …). Install it once from the [ContextMint Bridge releases](https://github.com/nullnet-app/contextmint-bridge/releases):

- **Chrome:** download the Chrome zip, unzip it, then `chrome://extensions` → toggle Developer mode → Load unpacked → pick the unzipped folder.
- **Safari:** not available yet — it will ship inside the ContextMint app, which has no public download. Use Chrome for now.

ContextMint Bridge is the fetchproxy browser extension under its new name, from the same maintainer — fetchproxy's own README ([Install → Extension](https://github.com/chrischall/fetchproxy#extension)) points to it. Its source is public at [nullnet-app/contextmint-bridge](https://github.com/nullnet-app/contextmint-bridge): build it yourself (see that repo's README), or check a release zip against the `.sha256` file published beside it before loading it — `shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256`.

Open zillow.com and sign in. That's all the auth this server needs.

## How it works

```
┌────────────────┐  stdio   ┌──────────────────┐   WS   ┌──────────────────┐    fetch()    ┌─────────────┐
│ MCP client     │◀────────▶│  dist/bundle.js  │◀──────▶│  ContextMint     │◀────────────▶│ zillow.com  │
│ (Claude, etc.) │          │  (Zillow MCP)    │ :37149 │  Bridge          │   (real TLS, │ (your tab)  │
└────────────────┘          └──────────────────┘        │  (separate)      │   cookies)    └─────────────┘
```

The MCP server runs in Node, but every HTTP call to zillow.com is dispatched into your live browser tab through the ContextMint Bridge extension. Each request rides your existing session — `_abck`, TLS fingerprint, and cookies 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.

## Commands

```bash
npm test               # vitest, mocked transport, no network
npm run test:watch
npm run test:coverage
npm run build          # tsc --noEmit + esbuild bundle → dist/bundle.js
npm run dev            # node dist/bundle.js (after build)
```

## License

MIT