zillow-mcp 0.1.0 → 0.2.1

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.1.0"
+    "version": "0.2.1"
   },
   "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.1.0",
+      "version": "0.2.1",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "zillow-mcp",
   "displayName": "Zillow",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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

@@ -17,13 +17,13 @@ None of them can see what *you* have saved, favorited, or recently viewed — be
 
 | Tool | Purpose | Auth-scoped |
 | --- | --- | :---: |
-| `zillow_search_properties` | Search listings by location and filters | |
-| `zillow_get_property` | Full record for a zpid (price, Zestimate, beds, schools, history) | |
-| `zillow_get_zestimate_history` | Time series of Zestimate values | |
-| `zillow_get_saved_searches` | Your saved searches with new-listing counts | ✓ |
-| `zillow_get_saved_homes` | Your favorited homes | ✓ |
-| `zillow_get_market_report` | Median price, days on market, ZHVI for a region | |
-| `zillow_calculate_mortgage` | Local PITI calculator (no network) | |
+| `zillow_search_properties` | Search listings by location, status, price band, beds/baths, home type | |
+| `zillow_get_property` | Full record for a zpid (price, Zestimate, beds, schools, neighborhood, price history) | |
+| `zillow_get_zestimate_history` | Time series of Zestimate values (and rent Zestimate where available) | |
+| `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 | ✓ |
+| `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) | |
 
 ## Install
 

package/dist/bundle.js

@@ -34704,10 +34704,7 @@ var ZillowClient = class {
     );
   }
   throwIfSignInPage(result) {
-    const signInMarkers = ["/user/login", "captcha-delivery"];
-    const looksLikeSignIn = /\/user\/login/.test(result.url) || /[?&]login=true/.test(result.url) || signInMarkers.some(
-      (m) => result.body.includes(m) && result.body.length < 8e4
-    );
+    const looksLikeSignIn = /\/user\/login/.test(result.url) || /[?&]login=true/.test(result.url) || result.body.includes("captcha-delivery") && result.body.length < 8e4;
     if (looksLikeSignIn) throw new SessionNotAuthenticatedError();
   }
 };
@@ -36763,8 +36760,14 @@ function registerSearchTools(server2, client2) {
   server2.registerTool(
     "zillow_search_properties",
     {
-      description: "Search Zillow listings by location (city, ZIP, neighborhood, or address) and optional filters. Returns matching properties with price, beds/baths, sqft, Zestimate, and the homedetails URL. Does NOT return Zestimate history \u2014 use zillow_get_zestimate_history for that.",
-      annotations: { readOnlyHint: true },
+      title: "Search Zillow listings",
+      description: "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. Does NOT return Zestimate history \u2014 use zillow_get_zestimate_history for that. Read-only; safe to call repeatedly.",
+      annotations: {
+        title: "Search Zillow listings",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
       inputSchema: {
         location: external_exports.string().describe(
           'Free-text location: city, ZIP, neighborhood, or address (e.g. "Brooklyn, NY", "94110", "Park Slope")'
@@ -36833,6 +36836,16 @@ function getPageProps(nextData) {
   return pageProps ?? {};
 }
 
+// src/url.ts
+function urlToPath(input) {
+  try {
+    const u = new URL(input);
+    return `${u.pathname}${u.search}`;
+  } catch {
+    return input.startsWith("/") ? input : `/${input}`;
+  }
+}
+
 // src/tools/properties.ts
 function findPropertyInPageProps(pageProps) {
   const cacheRaw = pageProps.gdpClientCache ?? pageProps.componentProps?.gdpClientCache;
@@ -36843,23 +36856,19 @@ function findPropertyInPageProps(pageProps) {
   } catch {
     return null;
   }
+  for (const [key, v] of Object.entries(cache)) {
+    if (key.startsWith("Property:") && v && typeof v === "object" && v.property) {
+      return v.property;
+    }
+  }
   for (const v of Object.values(cache)) {
     if (v && typeof v === "object" && v.property) return v.property;
   }
   return null;
 }
 function buildPath(args) {
-  if (args.url) {
-    try {
-      const u = new URL(args.url);
-      return `${u.pathname}${u.search}`;
-    } catch {
-      return args.url.startsWith("/") ? args.url : `/${args.url}`;
-    }
-  }
-  if (args.zpid !== void 0) {
-    return `/homedetails/${args.zpid}_zpid/`;
-  }
+  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");
 }
 function format(raw) {
@@ -36869,6 +36878,7 @@ function format(raw) {
     zpid,
     url: url2,
     address: raw.address,
+    neighborhood: raw.address?.neighborhood,
     price: raw.price,
     zestimate: raw.zestimate,
     rent_zestimate: raw.rentZestimate,
@@ -36895,8 +36905,14 @@ function registerPropertyTools(server2, client2) {
   server2.registerTool(
     "zillow_get_property",
     {
-      description: "Fetch a property's full Zillow record by zpid (e.g. 12345) or by homedetails URL. Returns address, price, Zestimate, beds/baths, square footage, year built, schools, and price history. Provide exactly one of zpid or url.",
-      annotations: { readOnlyHint: true },
+      title: "Get Zillow property details",
+      description: "Fetch a property's full Zillow record by zpid (numeric Zillow Property ID, e.g. 12345) or by homedetails URL. Returns address, neighborhood, price, Zestimate, rent Zestimate, beds/baths, square footage, year built, schools, and price history. Provide exactly one of zpid or url. Read-only; safe to call repeatedly.",
+      annotations: {
+        title: "Get Zillow property details",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
       inputSchema: {
         zpid: external_exports.union([external_exports.number().int().positive(), external_exports.string()]).optional().describe("Zillow Property ID (numeric)"),
         url: external_exports.string().optional().describe("A Zillow homedetails URL (or path beginning with /homedetails/)")
@@ -36949,48 +36965,76 @@ function registerZestimateTools(server2, client2) {
   server2.registerTool(
     "zillow_get_zestimate_history",
     {
-      description: "Historical Zestimate values for a property, by zpid. Returns a time series of {date, value, rent?} entries. Pulls from the same homedetails page as zillow_get_property \u2014 if you've already fetched the property, you have this data too.",
-      annotations: { readOnlyHint: true },
+      title: "Get Zestimate history for a property",
+      description: "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 \u2014 call this tool when you need the trend. Read-only; safe to call repeatedly.",
+      annotations: {
+        title: "Get Zestimate history for a property",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
       inputSchema: {
-        zpid: external_exports.union([external_exports.number().int().positive(), external_exports.string()]).describe("Zillow Property ID")
+        zpid: external_exports.union([external_exports.number().int().positive(), external_exports.string()]).optional().describe("Zillow Property ID. Provide either zpid or url."),
+        url: external_exports.string().optional().describe(
+          "Zillow homedetails URL (or path). Provide either zpid or url."
+        )
       }
     },
-    async ({ zpid }) => {
-      const html = await client2.fetchHtml(`/homedetails/${zpid}_zpid/`);
+    async ({ zpid, url: url2 }) => {
+      const path = url2 ? urlToPath(url2) : zpid !== void 0 ? `/homedetails/${zpid}_zpid/` : null;
+      if (!path) {
+        throw new Error(
+          "zillow_get_zestimate_history: must provide either zpid or url"
+        );
+      }
+      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__ for zpid=${zpid}.`
+          `Could not locate property data in __NEXT_DATA__ at ${path}.`
         );
       }
       const series = extractZestimateHistory(property);
-      return textResult({ zpid: String(zpid), points: series });
+      return textResult({
+        zpid: String(property.zpid ?? zpid ?? ""),
+        points: series
+      });
     }
   );
 }
 
-// src/tools/saved.ts
-function findSavedSearches(pageProps) {
-  const direct = pageProps.savedSearches ?? pageProps.userSavedSearches;
-  if (Array.isArray(direct)) return direct;
+// src/page-props.ts
+function findArrayByShape(pageProps, directKeys, shapeMatches) {
+  for (const key of directKeys) {
+    const candidate = pageProps[key];
+    if (Array.isArray(candidate)) return candidate;
+  }
   for (const v of Object.values(pageProps)) {
-    if (Array.isArray(v) && v.length > 0 && typeof v[0] === "object" && v[0] !== null && ("searchQueryState" in v[0] || "filterState" in v[0])) {
+    if (Array.isArray(v) && v.length > 0 && typeof v[0] === "object" && v[0] !== null && shapeMatches(v[0])) {
       return v;
     }
   }
   return [];
 }
+
+// src/tools/saved.ts
+var SAVED_SEARCH_KEYS = ["savedSearches", "userSavedSearches"];
+var SAVED_HOME_KEYS = ["savedHomes", "userSavedHomes", "favoriteHomes"];
+function findSavedSearches(pageProps) {
+  return findArrayByShape(
+    pageProps,
+    SAVED_SEARCH_KEYS,
+    (el) => "searchQueryState" in el || "filterState" in el
+  );
+}
 function findSavedHomes(pageProps) {
-  const direct = pageProps.savedHomes ?? pageProps.userSavedHomes ?? pageProps.favoriteHomes;
-  if (Array.isArray(direct)) return direct;
-  for (const v of Object.values(pageProps)) {
-    if (Array.isArray(v) && v.length > 0 && typeof v[0] === "object" && v[0] !== null && "zpid" in v[0] && ("hdpUrl" in v[0] || "savedAt" in v[0])) {
-      return v;
-    }
-  }
-  return [];
+  return findArrayByShape(
+    pageProps,
+    SAVED_HOME_KEYS,
+    (el) => "zpid" in el && ("hdpUrl" in el || "savedAt" in el)
+  );
 }
 function formatSearch(raw) {
   return {
@@ -37025,8 +37069,14 @@ function registerSavedTools(server2, client2) {
   server2.registerTool(
     "zillow_get_saved_searches",
     {
-      description: "The signed-in user's saved searches (name, filters, new-listing count, notification frequency). Requires being signed in to zillow.com in the bridged browser tab.",
-      annotations: { readOnlyHint: true },
+      title: "Get my saved Zillow searches",
+      description: "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 \u2014 throws SessionNotAuthenticatedError otherwise. Read-only; safe to call repeatedly.",
+      annotations: {
+        title: "Get my saved Zillow searches",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
       inputSchema: {}
     },
     async () => {
@@ -37040,8 +37090,14 @@ function registerSavedTools(server2, client2) {
   server2.registerTool(
     "zillow_get_saved_homes",
     {
-      description: "The signed-in user's saved (favorited) homes. Returns address, price, Zestimate, status, and when the home was saved. Requires being signed in.",
-      annotations: { readOnlyHint: true },
+      title: "Get my saved (favorited) Zillow homes",
+      description: "The signed-in user's saved (favorited) homes on zillow.com. Returns address, price, Zestimate, status, and when each home was saved. Requires the user to be signed in. Read-only; safe to call repeatedly.",
+      annotations: {
+        title: "Get my saved (favorited) Zillow homes",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
       inputSchema: {}
     },
     async () => {
@@ -37087,17 +37143,10 @@ function format2(raw) {
   };
 }
 function pathFromInput(args) {
-  if (args.url) {
-    try {
-      const u = new URL(args.url);
-      return `${u.pathname}${u.search}`;
-    } catch {
-      return args.url.startsWith("/") ? args.url : `/${args.url}`;
-    }
-  }
+  if (args.url) return urlToPath(args.url);
   if (args.region_path) {
-    const p = args.region_path.startsWith("/") ? args.region_path : `/${args.region_path}`;
-    return p.includes("/home-values/") ? p : `/home-values${p.startsWith("/") ? p : `/${p}`}`;
+    const p = urlToPath(args.region_path);
+    return p.includes("/home-values/") ? p : `/home-values${p}`;
   }
   throw new Error(
     'zillow_get_market_report: provide either region_path (e.g. "/home-values/6181/brooklyn-ny/") or url.'
@@ -37107,8 +37156,14 @@ function registerMarketTools(server2, client2) {
   server2.registerTool(
     "zillow_get_market_report",
     {
-      description: 'Market report for a Zillow region: median sale/list/rent prices, days on market, inventory, Zillow Home Value Index (ZHVI). Provide either a region_path (e.g. "/home-values/6181/brooklyn-ny/") or a full Zillow home-values URL.',
-      annotations: { readOnlyHint: true },
+      title: "Get Zillow market report for a region",
+      description: 'Market report for a Zillow region: median sale/list/rent prices, days on market, inventory, Zillow Home Value Index (ZHVI), year-over-year ZHVI change, and buyer/seller balance. 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.',
+      annotations: {
+        title: "Get Zillow market report for a region",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      },
       inputSchema: {
         region_path: external_exports.string().optional().describe(
           'Path under /home-values/, e.g. "/home-values/6181/brooklyn-ny/" or "6181/brooklyn-ny/"'
@@ -37185,8 +37240,14 @@ function registerMortgageTools(server2) {
   server2.registerTool(
     "zillow_calculate_mortgage",
     {
-      description: "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. 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.",
-      annotations: { readOnlyHint: true },
+      title: "Calculate mortgage payment (local)",
+      description: "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 \u2014 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.",
+      annotations: {
+        title: "Calculate mortgage payment (local)",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      },
       inputSchema: {
         home_price: external_exports.number().positive(),
         down_payment: external_exports.number().nonnegative().optional(),
@@ -37205,7 +37266,7 @@ function registerMortgageTools(server2) {
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.1";
 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 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zillow-mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.chrischall/zillow-mcp",
-  "description": "Zillow real-estate access for Claude — search listings, fetch property details, Zestimate history, saved searches & homes, market reports. Auth via the user's signed-in zillow.com browser tab through the fetchproxy extension.",
+  "description": "Zillow real-estate for Claude — search, property details, Zestimates, saved searches & homes",
   "repository": {
     "url": "https://github.com/chrischall/zillow-mcp",
     "source": "github"
   },
-  "version": "0.1.0",
+  "version": "0.2.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "zillow-mcp",
-      "version": "0.1.0",
+      "version": "0.2.1",
       "transport": {
         "type": "stdio"
       },