zillow-mcp

zillow-mcp

将 Zillow 房地产服务接入为 Claude 的 MCP 服务——通过自然语言搜索房源、获取房产详情、Zestimate 历史记录、已保存的搜索和房屋，以及市场报告。

⚠️ Zillow 不提供面向公众的消费者 API。官方 Bridge API 仅向 MLS 合作伙伴开放。此服务使用与 zillow.com 网页应用相同的私有端点，并通过 ContextMint Bridge 浏览器扩展，经由你已登录的浏览器标签页发送请求。每个请求都以你现有会话的身份发出——使用你的 Cookie、TLS 和 JS 上下文——就像你亲自在浏览器中点击一样。请将此服务视为对 Zillow 网站的非正式使用。使用风险自负。

为什么要开发它

现有的四个 Zillow MCP 服务都基于以下两种方式之一：

• Bridge API——需要 MLS 会员资格、IDX 供应商关系或“获批的技术合作伙伴”身份（审批需要 10 个以上工作日）。消费者无法使用。
• 付费爬虫（RapidAPI、Apify）——让第三方加入信任链路，并限制请求速率。

它们都无法查看你已保存、收藏或最近浏览的内容——因为 Bridge 和第三方爬虫都不在你的登录会话中。zillow-mcp 使用的是你已登录的 zillow.com 标签页。

工具

工具	用途	按身份验证范围限定
zillow_search_properties	按位置、状态、价格范围、卧室/浴室数量和房屋类型搜索房源。可选的 map_bounds 视口；include_meta 会报告 Zillow 自身的总数与已获取数量，以便查看结果是否被截断
zillow_sweep_area	穷尽枚举某个区域：递归划分地图，直到所有图块都未被截断；去重，并提供完整性摘要和数据偏差警告；可选输出 JSON 文件
zillow_get_property	获取 zpid 的完整记录（价格、Zestimate、卧室、学校、社区、价格历史）
zillow_get_by_address	将自由文本地址（可选城市/州/邮政编码）解析为 Zillow zpid 和规范 URL
zillow_resolve_addresses	批量将多个自由文本地址（或结构化行）解析为 zpid 和规范 URL
zillow_bulk_get	一次获取多个 zpid/URL 的完整记录，并处理部分结果和机器人拦截
zillow_get_property_photos	房屋的完整照片集——homedetails 页面中嵌入的每张图片，包含多种宽度的 jpeg 和 webp 版本及说明
zillow_get_zestimate_history	Zestimate 值的时间序列（以及可用时的租金 Zestimate）
zillow_get_price_history	房源历史记录（Listed/Sold/Pending 等），包含价格和上市天数
zillow_get_tax_history	年度税务记录历史——逐年缴纳的税款和评估价值
zillow_compare_properties	并排比较最多 12 套房产，并提供对齐的摘要表格
zillow_calculate_affordability	本地购房负担能力计算器——根据收入、DTI 和利率计算最高购买价格
zillow_estimate_rent_vs_buy	本地租房与买房盈亏平衡计算，考虑升值和机会成本
zillow_get_saved_searches	你保存的搜索，包含新房源数量和通知频率	✓
zillow_get_saved_homes	你收藏的房屋，包含当前价格、Zestimate 和主照片	✓
zillow_get_market_report	某个区域的销售/挂牌/租金中位数、上市天数、库存和 ZHVI
zillow_calculate_mortgage	本地 PITI 计算器——本金+利息、税费、保险、HOA、PMI（不联网）
zillow_healthcheck	通过桥接服务往返访问公开的 Zillow URL，以定位桥接服务/扩展程序/Zillow 端故障
zillow_register_session	在本地会话注册表中记录已登录标签页所属的 Zillow 账户（仅作标签）
zillow_set_active_session	将已注册的会话标记为当前账户标签——不会更改请求所使用的账户（每次调用都会通过已登录的浏览器标签页进行）
zillow_get_session_context	检查活动会话和已注册会话列表

输入和输出约定

工具输入和输出的变更，方便你调整调用这些工具的脚本或提示词：

• zillow_compare_properties 现在会像 zillow_bulk_get 一样报告遇到机器人拦截的行。 对于 Zillow 持续通过验证码拦截的行，现在会返回 error_kind: "bot_challenge"，而不是通用错误类型，方便你将其与房源缺失区分开来。响应还可能包含 blocked（仍被拦截的行数）、retry_after_s（重试这些行前应等待的秒数）和 pending（未能在总截止时间前完成的行数；这些行的 error_kind 为 "pending"）。

• zpid 必须是数字。 所有接收 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）都接受正整数，或仅包含数字的字符串，例如 "12345"。任何其他字符串，例如 "12345_zpid" 或 URL，现在都会被判定为无效输入。请改为在 url 或 urls 字段中传入房源详情页 URL。

• 请传入 zpids 或 urls，不要同时传入两者。 zillow_bulk_get 和 zillow_compare_properties 现在会在一次调用同时包含两个列表时返回错误。此前，urls 列表会被静默忽略。如需获取这两类数据，请分两次调用。

条款确认

使用此 MCP 服务，即表示你确认并同意以下内容：

1. 此服务访问的是你自己的 Zillow 会话。 每个请求都会通过 ContextMint Bridge 扩展，经由你自己的浏览器标签页（无论是否已登录）发出。它不会，也无法访问其他人的账户。

2. Zillow 的使用条款适用于你对本服务的使用，就像它们适用于你直接使用 zillow.com 一样。与此最相关的条款如下：

未经我们明确书面许可，你不得出于任何目的使用任何机器人、蜘蛛程序、抓取工具或其他自动化方式访问服务……也不得执行自动化查询（包括屏幕和数据库抓取、蜘蛛程序、机器人、爬虫、绕过验证码或类似防护措施）。

每次调用此服务中的工具，即表示你同意这些条款——维护者于 2026-05-23 阅读了这些条款。Zillow 的条款广泛禁止未经书面许可的自动访问；这是一个非官方工具，Zillow 并未授予其使用许可。

3. 仅限个人非商业用途。 本项目与 Zillow Group 无关联，也未获其认可、赞助或与其合作。它是一款个人自动化工具，用于操作与您手动访问时相同的 Zillow 网站——一次搜索、你自己收藏的房屋、你自己的市场报告。请勿用它批量提取房源、训练模型、填充竞争对手的房地产产品，或用于任何商业目的。

4. 不保证稳定性。 此服务会读取私有内部端点（/async-create-search-page-state/、__NEXT_DATA__ 数据块、/myzillow/...），Zillow 可能随时更改这些端点。服务可能会出故障，也可能停止工作。这是设计如此——这些接口并非由 Zillow 维护来为我们提供支持。

5. 你须对因使用此服务访问 Zillow 而产生的任何后果承担全部责任——包括限流、账户警告、暂停使用、IP 封禁、验证码拦截，或 Zillow Group 采取的任何执法行动。如果 Zillow 对你的使用提出异议，请停止使用此服务。

本节是维护者本着诚意对相关条款所作的摘要；它不构成法律建议，也不会修改或取代 Zillow 的实际服务条款。

安装

选项 A — npx（发布后）

添加到 .mcp.json：

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

选项 B — 从源码安装

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

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

一次性浏览器设置

zillow-mcp 通过 ContextMint Bridge 扩展与浏览器通信，该扩展由所有基于 fetchproxy 的 MCP（resy-mcp、opentable-mcp、……）共用。从 ContextMint Bridge releases 安装一次即可：

• Chrome： 下载 Chrome 压缩包并解压，然后打开 chrome://extensions → 切换“开发者模式” →“加载已解压的扩展程序” → 选择解压后的文件夹。
• Safari： 暂不可用——它将随 ContextMint 应用一起发布，但该应用没有公开下载渠道。目前请使用 Chrome。

ContextMint Bridge 是 fetchproxy 浏览器扩展的新名称，由同一位维护者开发——fetchproxy 自己的 README（安装 → 扩展）也指向它。其源代码公开于 nullnet-app/contextmint-bridge：你可以自行构建（参见该仓库的 README），也可以在加载发布压缩包前，将其与旁边发布的 .sha256 文件进行校验——shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256。

打开 zillow.com 并登录。该服务所需的身份验证就完成了。

工作原理

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

MCP 服务运行在 Node 中，但所有发往 zillow.com 的 HTTP 调用都会通过 ContextMint Bridge 扩展，转发到你当前打开的浏览器标签页。每个请求都会使用你现有的会话——_abck、TLS 指纹和 Cookie 都与屏幕上已打开的页面一致。没有无头浏览器替身，没有独立身份，也没有第三方代理：只有你的真实浏览器自行发起请求，由 MCP 服务决定要请求什么。

命令

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)

许可证

MIT