zillow-mcp 0.2.2 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Zillow — search listings, fetch property details, Zestimate history, saved searches & homes, market reports. Routes through the user's signed-in zillow.com tab via the fetchproxy browser extension to dodge bot detection.",
-    "version": "0.2.2"
+    "version": "0.3.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Zillow",
       "source": "./",
       "description": "MCP server for Zillow — search listings, get property details, Zestimate history, saved searches & homes, market reports",
-      "version": "0.2.2",
+      "version": "0.3.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "zillow-mcp",
   "displayName": "Zillow",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Zillow real-estate access for Claude — search listings, get property details, Zestimate history, your saved searches & homes, market reports",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -25,6 +25,26 @@ None of them can see what *you* have saved, favorited, or recently viewed — be
 | `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) | |
 
+## 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 fetchproxy 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)

package/dist/bundle.js

@@ -36873,7 +36873,20 @@ function findPropertyInPageProps(pageProps) {
 function buildPath(args) {
   if (args.url) return urlToPath(args.url);
   if (args.zpid !== void 0) return `/homedetails/${args.zpid}_zpid/`;
-  throw new Error("zillow_get_property: must provide either zpid or url");
+  throw new Error("zillow property tool: must provide either zpid or url");
+}
+async function fetchPropertyRecord(client2, args) {
+  const path = buildPath(args);
+  const html = await client2.fetchHtml(path);
+  const nextData = extractNextData(html);
+  const pageProps = getPageProps(nextData);
+  const property = findPropertyInPageProps(pageProps);
+  if (!property) {
+    throw new Error(
+      `Could not locate property data in __NEXT_DATA__ at ${path}. Zillow may have changed their page structure.`
+    );
+  }
+  return { raw: property, path };
 }
 function format(raw) {
   const zpid = String(raw.zpid ?? "");
@@ -36923,17 +36936,8 @@ function registerPropertyTools(server2, client2) {
       }
     },
     async ({ zpid, url: url2 }) => {
-      const path = buildPath({ zpid, url: url2 });
-      const html = await client2.fetchHtml(path);
-      const nextData = extractNextData(html);
-      const pageProps = getPageProps(nextData);
-      const property = findPropertyInPageProps(pageProps);
-      if (!property) {
-        throw new Error(
-          `Could not locate property data in __NEXT_DATA__ at ${path}. Zillow may have changed their page structure.`
-        );
-      }
-      return textResult(format(property));
+      const { raw } = await fetchPropertyRecord(client2, { zpid, url: url2 });
+      return textResult(format(raw));
     }
   );
 }
@@ -37280,8 +37284,338 @@ function registerMortgageTools(server2) {
   );
 }
 
+// src/tools/history.ts
+function toPercent(rate) {
+  if (typeof rate !== "number") return void 0;
+  return Math.round(rate * 1e3) / 10;
+}
+function formatPriceEvent(raw) {
+  const date5 = raw.date ?? (typeof raw.time === "number" ? new Date(raw.time).toISOString().slice(0, 10) : void 0);
+  return {
+    date: date5,
+    event: raw.event,
+    price: raw.price,
+    price_change_percent: toPercent(raw.priceChangeRate),
+    price_per_sqft: raw.pricePerSquareFoot,
+    source: raw.source,
+    mls_number: raw.attributeSource?.infoString1
+  };
+}
+function formatTaxEvent(raw) {
+  const year = typeof raw.time === "number" ? new Date(raw.time).getUTCFullYear() : void 0;
+  return {
+    year,
+    tax_paid: raw.taxPaid,
+    tax_increase_percent: toPercent(raw.taxIncreaseRate),
+    assessed_value: raw.value,
+    assessed_value_increase_percent: toPercent(raw.valueIncreaseRate)
+  };
+}
+function registerHistoryTools(server2, client2) {
+  server2.registerTool(
+    "zillow_get_price_history",
+    {
+      title: "Get Zillow price history for a property",
+      description: "Listing-price events for a property \u2014 listings, price changes, pending, sold, etc. \u2014 by zpid or homedetails URL. Each entry has a date, event type, price, percent price-change, price/sqft, and MLS attribution. Sourced from the same homedetails page as zillow_get_property, but returns just the price-history series for easier downstream reasoning.",
+      annotations: {
+        title: "Get Zillow price history for a property",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      inputSchema: {
+        zpid: external_exports.union([external_exports.number().int().positive(), external_exports.string()]).optional().describe("Zillow Property ID"),
+        url: external_exports.string().optional().describe("Zillow homedetails URL or path")
+      }
+    },
+    async ({ zpid, url: url2 }) => {
+      const { raw } = await fetchPropertyRecord(client2, { zpid, url: url2 });
+      const events = (raw.priceHistory ?? []).map(formatPriceEvent);
+      return textResult({ zpid: String(raw.zpid ?? zpid ?? ""), events });
+    }
+  );
+  server2.registerTool(
+    "zillow_get_tax_history",
+    {
+      title: "Get Zillow tax history for a property",
+      description: "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.",
+      annotations: {
+        title: "Get Zillow tax history for a property",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      inputSchema: {
+        zpid: external_exports.union([external_exports.number().int().positive(), external_exports.string()]).optional().describe("Zillow Property ID"),
+        url: external_exports.string().optional().describe("Zillow homedetails URL or path")
+      }
+    },
+    async ({ zpid, url: url2 }) => {
+      const { raw } = await fetchPropertyRecord(client2, { zpid, url: url2 });
+      const events = (raw.taxHistory ?? []).map(formatTaxEvent);
+      return textResult({ zpid: String(raw.zpid ?? zpid ?? ""), events });
+    }
+  );
+}
+
+// src/tools/compare.ts
+function buildSummary(rows) {
+  const pick2 = (label, fn) => ({
+    field: label,
+    values: rows.map((r) => r.property ? fn(r.property) ?? null : null)
+  });
+  return [
+    pick2("price", (p) => p.price),
+    pick2("zestimate", (p) => p.zestimate),
+    pick2("rent_zestimate", (p) => p.rent_zestimate),
+    pick2("beds", (p) => p.beds),
+    pick2("baths", (p) => p.baths),
+    pick2("living_area_sqft", (p) => p.living_area),
+    pick2("lot_size_sqft", (p) => p.lot_size),
+    pick2("year_built", (p) => p.year_built),
+    pick2("home_type", (p) => p.home_type),
+    pick2("status", (p) => p.status),
+    pick2("days_on_zillow", (p) => p.days_on_zillow),
+    pick2("tax_assessed_value", (p) => p.tax_assessed_value),
+    pick2("neighborhood", (p) => p.neighborhood)
+  ];
+}
+function registerCompareTools(server2, client2) {
+  server2.registerTool(
+    "zillow_compare_properties",
+    {
+      title: "Compare multiple Zillow properties side-by-side",
+      description: "Fetch and compare 2 or more Zillow properties side-by-side. Provide an array of zpids (or homedetails URLs). Returns a compact summary table aligned by field (price, beds/baths, sqft, year built, Zestimate, etc.) plus the full per-property record. Errors for individual properties are captured per-row \u2014 one bad zpid won't fail the whole call. Calls are concurrent.",
+      annotations: {
+        title: "Compare multiple Zillow properties side-by-side",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      inputSchema: {
+        zpids: external_exports.array(external_exports.union([external_exports.number().int().positive(), external_exports.string()])).min(2).max(8).optional().describe(
+          "Array of 2\u20138 zpids to compare. Provide either zpids or urls."
+        ),
+        urls: external_exports.array(external_exports.string()).min(2).max(8).optional().describe(
+          "Array of 2\u20138 Zillow homedetails URLs/paths to compare. Provide either zpids or urls."
+        )
+      }
+    },
+    async ({ zpids, urls }) => {
+      const targets = zpids && zpids.length > 0 ? zpids.map((zpid) => ({ zpid })) : urls && urls.length > 0 ? urls.map((url2) => ({ url: url2 })) : null;
+      if (!targets || targets.length < 2) {
+        throw new Error(
+          "zillow_compare_properties: provide an array of at least 2 zpids or urls."
+        );
+      }
+      const results = await Promise.all(
+        targets.map(async (t) => {
+          const fallbackZpid = "zpid" in t ? String(t.zpid) : "";
+          try {
+            const { raw } = await fetchPropertyRecord(client2, t);
+            return {
+              zpid: String(raw.zpid ?? fallbackZpid),
+              property: format(raw)
+            };
+          } catch (e) {
+            return { zpid: fallbackZpid, error: e.message };
+          }
+        })
+      );
+      return textResult({
+        count: results.length,
+        summary: buildSummary(results),
+        results
+      });
+    }
+  );
+}
+
+// src/tools/affordability.ts
+function computeAffordability(input) {
+  if (input.monthly_income <= 0)
+    throw new Error("monthly_income must be positive");
+  if (input.down_payment < 0) throw new Error("down_payment must be >= 0");
+  if (input.interest_rate < 0)
+    throw new Error("interest_rate must be >= 0");
+  const term_years = input.loan_term_years ?? 30;
+  const monthly_debts = input.monthly_debts ?? 0;
+  const front_dti = input.front_end_dti ?? 0.28;
+  const back_dti = input.back_end_dti ?? 0.36;
+  const tax_rate = input.property_tax_rate ?? 1.1;
+  const insurance_annual = input.insurance_annual ?? 0;
+  const hoa_monthly = input.hoa_monthly ?? 0;
+  const front_max = input.monthly_income * front_dti;
+  const back_max = input.monthly_income * back_dti - monthly_debts;
+  const max_piti = Math.max(0, Math.min(front_max, back_max));
+  const binding = front_max <= back_max ? "front_end" : "back_end";
+  const monthly_ins = insurance_annual / 12;
+  const monthly_tax_per_dollar = tax_rate / 100 / 12;
+  const monthly_pi_budget = Math.max(
+    0,
+    max_piti - monthly_ins - hoa_monthly
+  );
+  const r = input.interest_rate / 100 / 12;
+  const n = term_years * 12;
+  const factor = r === 0 ? 1 / n : r * Math.pow(1 + r, n) / (Math.pow(1 + r, n) - 1);
+  const coeff = monthly_tax_per_dollar + factor;
+  const max_home_price = coeff === 0 ? input.down_payment : (monthly_pi_budget + input.down_payment * factor) / coeff;
+  const loan_amount = Math.max(0, max_home_price - input.down_payment);
+  const monthly_pi = r === 0 ? loan_amount / n : loan_amount * factor;
+  const monthly_tax = max_home_price * monthly_tax_per_dollar;
+  return {
+    max_home_price: round22(max_home_price),
+    max_monthly_piti: round22(max_piti),
+    binding_constraint: binding,
+    monthly_principal_interest: round22(monthly_pi),
+    monthly_property_tax: round22(monthly_tax),
+    monthly_insurance: round22(monthly_ins),
+    monthly_hoa: round22(hoa_monthly),
+    loan_amount: round22(loan_amount),
+    down_payment: round22(input.down_payment),
+    front_end_dti_used: front_dti,
+    back_end_dti_used: back_dti
+  };
+}
+function computeRentVsBuy(input) {
+  if (input.home_price <= 0) throw new Error("home_price must be positive");
+  if (input.monthly_rent <= 0)
+    throw new Error("monthly_rent must be positive");
+  const horizon = input.horizon_years ?? 7;
+  if (horizon <= 0) throw new Error("horizon_years must be positive");
+  const term_years = input.loan_term_years ?? 30;
+  const r = input.interest_rate / 100 / 12;
+  const n = term_years * 12;
+  const loan = Math.max(0, input.home_price - input.down_payment);
+  const monthly_pi = r === 0 ? loan / n : loan * (r * Math.pow(1 + r, n)) / (Math.pow(1 + r, n) - 1);
+  const closing = input.home_price * ((input.closing_cost_rate ?? 2.5) / 100);
+  const selling_rate = (input.selling_cost_rate ?? 6) / 100;
+  const tax_rate = (input.property_tax_rate ?? 1.1) / 100;
+  const insurance = input.insurance_annual ?? 0;
+  const hoa = (input.hoa_monthly ?? 0) * 12;
+  const maint_rate = (input.maintenance_rate ?? 1) / 100;
+  const appreciation = (input.appreciation_rate ?? 3) / 100;
+  const rent_growth = (input.rent_growth_rate ?? 3) / 100;
+  const invest_return = (input.investment_return_rate ?? 6) / 100;
+  let cum_buy = input.down_payment + closing;
+  let cum_rent = 0;
+  let invested = input.down_payment;
+  let home_value = input.home_price;
+  let principal_remaining = loan;
+  const yearly = [];
+  let break_even = null;
+  let final_net_after_sale = 0;
+  for (let y = 1; y <= horizon; y++) {
+    const year_pi = monthly_pi * 12;
+    const year_tax = home_value * tax_rate;
+    const year_maint = home_value * maint_rate;
+    cum_buy += year_pi + year_tax + insurance + hoa + year_maint;
+    let interest_paid = 0;
+    let principal_paid = 0;
+    for (let m = 0; m < 12; m++) {
+      const int_m = principal_remaining * r;
+      const pi_m = Math.min(monthly_pi, principal_remaining + int_m);
+      const prin_m = pi_m - int_m;
+      principal_remaining = Math.max(0, principal_remaining - prin_m);
+      interest_paid += int_m;
+      principal_paid += prin_m;
+    }
+    const year_rent = input.monthly_rent * 12 * Math.pow(1 + rent_growth, y - 1);
+    cum_rent += year_rent;
+    invested = invested * (1 + invest_return);
+    home_value = home_value * (1 + appreciation);
+    const sale_proceeds = home_value * (1 - selling_rate) - principal_remaining;
+    const buy_net_if_sold = cum_buy - sale_proceeds;
+    const renter_invest_growth = invested - input.down_payment;
+    const rent_net = cum_rent - renter_invest_growth;
+    if (break_even === null && buy_net_if_sold <= rent_net) break_even = y;
+    yearly.push({
+      year: y,
+      cumulative_buy_cost: round22(cum_buy),
+      cumulative_rent_cost: round22(cum_rent),
+      home_value: round22(home_value),
+      remaining_mortgage: round22(principal_remaining),
+      equity_if_sold_now: round22(home_value * (1 - selling_rate) - principal_remaining)
+    });
+    if (y === horizon) final_net_after_sale = buy_net_if_sold - rent_net;
+  }
+  return {
+    horizon_years: horizon,
+    buy_total_cost_after_sale: round22(
+      cum_buy - (home_value * (1 - selling_rate) - principal_remaining)
+    ),
+    rent_total_cost: round22(cum_rent - (invested - input.down_payment)),
+    net_difference: round22(final_net_after_sale),
+    buy_wins: final_net_after_sale < 0,
+    break_even_year: break_even,
+    yearly
+  };
+}
+function round22(n) {
+  return Math.round(n * 100) / 100;
+}
+function registerAffordabilityTools(server2) {
+  server2.registerTool(
+    "zillow_calculate_affordability",
+    {
+      title: "Calculate max affordable home price",
+      description: "Solve for the maximum home price you can afford under the standard 28/36 DTI rule. Inputs: monthly income, monthly recurring 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. No network \u2014 pure local math.",
+      annotations: {
+        title: "Calculate max affordable home price",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      },
+      inputSchema: {
+        monthly_income: external_exports.number().positive(),
+        monthly_debts: external_exports.number().nonnegative().optional().describe("Sum of monthly debt payments (car, student loans, etc.)"),
+        down_payment: external_exports.number().nonnegative(),
+        interest_rate: external_exports.number().nonnegative().describe("Annual %, e.g. 6.5"),
+        loan_term_years: external_exports.number().int().positive().optional().describe("Default 30"),
+        property_tax_rate: external_exports.number().nonnegative().optional().describe("Annual % of home price, default 1.1"),
+        insurance_annual: external_exports.number().nonnegative().optional(),
+        hoa_monthly: external_exports.number().nonnegative().optional(),
+        front_end_dti: external_exports.number().positive().max(1).optional().describe("Front-end DTI cap as decimal, default 0.28"),
+        back_end_dti: external_exports.number().positive().max(1).optional().describe("Back-end DTI cap as decimal, default 0.36")
+      }
+    },
+    async (input) => textResult(computeAffordability(input))
+  );
+  server2.registerTool(
+    "zillow_estimate_rent_vs_buy",
+    {
+      title: "Estimate rent-vs-buy break-even over a horizon",
+      description: "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). Returns the year-by-year cumulative costs, the break-even year, and the net difference at the horizon. No network \u2014 pure local math.",
+      annotations: {
+        title: "Estimate rent-vs-buy break-even over a horizon",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      },
+      inputSchema: {
+        home_price: external_exports.number().positive(),
+        down_payment: external_exports.number().nonnegative(),
+        interest_rate: external_exports.number().nonnegative(),
+        loan_term_years: external_exports.number().int().positive().optional(),
+        property_tax_rate: external_exports.number().nonnegative().optional(),
+        insurance_annual: external_exports.number().nonnegative().optional(),
+        hoa_monthly: external_exports.number().nonnegative().optional(),
+        maintenance_rate: external_exports.number().nonnegative().optional().describe("Annual % of home value, default 1.0"),
+        closing_cost_rate: external_exports.number().nonnegative().optional().describe("% of home price, default 2.5"),
+        selling_cost_rate: external_exports.number().nonnegative().optional().describe("% of sale price, default 6.0"),
+        appreciation_rate: external_exports.number().optional().describe("Annual %, default 3.0"),
+        monthly_rent: external_exports.number().positive(),
+        rent_growth_rate: external_exports.number().optional().describe("Annual %, default 3.0"),
+        investment_return_rate: external_exports.number().optional().describe("Annual return on the renter's parallel-invested down payment, default 6.0"),
+        horizon_years: external_exports.number().int().positive().optional().describe("Default 7")
+      }
+    },
+    async (input) => textResult(computeRentVsBuy(input))
+  );
+}
+
 // src/index.ts
-var VERSION = "0.2.2";
+var VERSION = "0.3.0";
 var port = process.env.ZILLOW_WS_PORT ? Number(process.env.ZILLOW_WS_PORT) : void 0;
 var transport = new FetchproxyTransport({ port, version: VERSION });
 var client = new ZillowClient({ transport });
@@ -37293,6 +37627,9 @@ registerZestimateTools(server, client);
 registerSavedTools(server, client);
 registerMarketTools(server, client);
 registerMortgageTools(server);
+registerHistoryTools(server, client);
+registerCompareTools(server, client);
+registerAffordabilityTools(server);
 console.error(
   `[zillow-mcp] v${VERSION} \u2014 WebSocket bridge via @fetchproxy/server on 127.0.0.1:${port ?? 37149}. Install the fetchproxy extension (see https://github.com/chrischall/fetchproxy) and sign into zillow.com. This project was developed and is maintained by AI (Claude). Use at your own discretion.`
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zillow-mcp",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "mcpName": "io.github.chrischall/zillow-mcp",
   "description": "Zillow MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/zillow-mcp",
     "source": "github"
   },
-  "version": "0.2.2",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "zillow-mcp",
-      "version": "0.2.2",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },