Zillow MCP 服务器

一个托管的模型上下文协议（MCP）服务器，为 Claude、Cursor、Windsurf 以及任何其他 MCP 客户端提供两个只读的 Zillow 工具。可使用丰富的筛选条件搜索在售、出租和已售房源，并完整读取单个房产信息，全部以结构化 JSON 返回，无需 Zillow 帐户，也无需自行托管任何内容。

它读取的是 Zillow.com 上未登录访客即可查看的公开房源页面。

https://mcp.hasdata.com/api/mcp?apis=zillow

目录

• 你需要什么

• 快速开始

• 示例提示词

• 工具

• 错误与失败路径

• 定价、免费额度与限制

• 工具选择

• 对比

• 常见问题

• HasData 链接

• 开发

• 参与贡献

• 许可证

你需要什么

一个 MCP 客户端，以及从控制台获取的 HasData API 密钥——免费创建，无需银行卡，试用额度按 5 积分/次的费率可覆盖约 200 次调用。这是一个远程服务器，因此最简单的接入方式是一个 URL 加 x-api-key 请求头，无需运行容器，整个流程中也不会用到 Zillow 帐户。仅支持 stdio 的客户端可以通过一个轻量启动器访问该服务器，该启动器以 @hasdata/zillow-mcp 发布在 npm 上，以 hasdata-zillow-mcp 发布在 PyPI 上，如下所示。

快速开始

服务器 URL 对所有客户端都是一样的。我们在 Claude Code 和 Claude Desktop 中进行了实际操作验证。其余配置块遵循各客户端自己文档中关于远程服务器的格式。

支持 OAuth 的客户端可以将同一个 URL 添加为连接器，然后直接登录，无需在配置文件中写入密钥。

claude mcp add --transport http zillow "https://mcp.hasdata.com/api/mcp?apis=zillow" \
  --header "x-api-key: HASDATA_API_KEY"

进入设置，然后选择连接器，再选择“添加自定义连接器”，粘贴 https://mcp.hasdata.com/api/mcp?apis=zillow 并登录。

如果走配置文件的方式，Claude Desktop 只加载本地（stdio）服务器，因此它需要通过 stdio 启动器访问远程服务器。@hasdata/zillow-mcp 就是这个启动器，它会从环境变量中读取密钥。将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "zillow": {
      "command": "npx",
      "args": ["-y", "@hasdata/zillow-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

如果使用 Python 而非 Node，可将该启动器替换为 PyPI 包，uvx 可以直接运行，无需手动安装：

{
  "mcpServers": {
    "zillow": {
      "command": "uvx",
      "args": ["hasdata-zillow-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

~/.cursor/mcp.json 适用于所有项目，或 .cursor/mcp.json 仅适用于单个项目：

{
  "mcpServers": {
    "zillow": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=zillow",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.codeium/windsurf/mcp_config.json。Windsurf 将字段称为 serverUrl，而非 url：

{
  "mcpServers": {
    "zillow": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=zillow",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

工作区中的 .vscode/mcp.json：

{
  "servers": {
    "zillow": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=zillow",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

示例提示词

这些是提示词，不是代码。粘贴一条，代理会自动选择工具。每条提示已标注其所需的调用次数，因为每次成功调用都会消耗 5 点积分。

搜索德克萨斯州奥斯汀市至少三居室、价格低于 60 万美元的在售房屋，按最新优先排序，并列出按价格和挂牌天数排序的最近十条。

一次调用，5 点积分。价格、卧室数、面积和挂牌天数会随搜索结果返回。

取出第一条结果并获取其完整详情：价格历史、税务历史、价格估算和分配的学校。

一次调用，5 点积分。这些数据位于房源页面上，详情工具会通过 URL 读取。

查找奥斯汀允许养猫的出租公寓，然后提取最便宜的三套的租金估算。

四次调用，20 点积分。一次搜索，然后对三条房源分别进行一次房产详情调用。

对于这个房产 URL，给出挂牌价、价格估算以及价格历史中的最近三次交易。

一次调用，5 点积分。

一条搜索结果足以用于排序和初步筛选。价格历史、税务历史、价格估算、学校数据和经纪人信息则来自房产详情调用，因此一个先筛选再查看三套房子的提示词就是一次搜索加三次房产详情调用。

工具

两个工具，均为只读。以下示例取自真实调用（已做精简），数字会随市场变化而变化。请将其视为数据结构示例。每个工具名称都链接到其端点参考文档，其中包含完整字段列表。

这些示例只是响应主体，而不是完整响应。tools/call 的结果包含一个数据文本块，该文本本身是 JSON，包含 url、status、text 和 json，其中抓取的数据位于 json 下。从原始 JSON-RPC 响应中，路径为 result.content[0].text，解析后再取 .json。聊天客户端会为你自动解包，而直接与端点交互的代码则不会。

获取 Zillow 房地产房源列表

hasdata_zillow_listing_getRealEstateListings

按关键城市地点筛选并返回一页房源列表。

参考文档还提供了 description、lotSize、yearBuilt 和 HOA 区间等更多字段，以及 otherAmenities__、views__、pets__、listingType、propertyStatus__、listingPublishOptions__ 等。

返回包含 totalResults 的 searchInformation、一个 properties 数组，以及包含 nextPage 的 pagination——nextPage 是下一页的 URL。每个房产都带有 id、url、homeType、status、price、currency、一个 rentZestimate 租金估算、daysOnZillow、以平方英尺计的 area、addressRaw 和结构化的 address、latitude、longitude、beds、baths、listingDetails、mediaDetails 和 photos。

{
  "id": "60134551",
  "url": "https://www.zillow.com/homedetails/6116-Speyside-Dr-Austin-TX-78754/60134551_zpid/",
  "homeType": "SINGLE_FAMILY",
  "status": "FOR_SALE",
  "price": 320000,
  "currency": "$",
  "rentZestimate": 2286,
  "daysOnZillow": 0,
  "area": 2277,
  "address": { "street": "6116 Speyside Dr", "city": "Austin", "state": "TX", "zipcode": "78754" },
  "beds": 4,
  "baths": 3
}

获取 Zillow 房产详情

hasdata_zillow_property_getPropertyDetails

通过 URL 获取单个房产的完整信息。

返回完整详情：price、currency、beds、baths、area、yearBuilt、homeType、mlsId、结构化的 address 和 geo、description 和 highlights、photos、schools、daysOnZillow、views、saves、agentInfo 数据块，以及 priceHistory、taxHistory 和 mortgage 数组。Zillow 自己的估值由 zestimate 对象返回，其中包含 zestimate、estimatedSaleRange 和 rentZestimate。请将其视为估算值，而非确认值。

注意：这里的 area 是一个属性，{ livingArea, livingAreaUnits }，而不是搜索工具返回的单一数值。在房产页面上请使用 area.livingArea 获取平方英尺，或者像 area > 2000 这样的数值比较会因对象类型而静默失败。

{
  "id": 60134551,
  "status": "FOR_SALE",
  "price": 320000,
  "currency": "USD",
  "yearBuilt": 2002,
  "beds": 4,
  "baths": 3,
  "area": { "livingArea": 2277, "livingAreaUnits": "Square Feet" },
  "fees": { "monthlyHoaFee": "$500 annually" },
  "zestimate": { "zestimate": 318100, "estimatedSaleRange": "$302K - $334K", "rentZestimate": 2286 },
  "address": { "street": "6116 Speyside Dr", "county": "Travis County" },
  "agentInfo": { "agentName": "Marie Coleman", "brokerName": "eXp Realty" },
  "priceHistory": [{ "date": "2026-08-24", "price": 320000, "event": "listedForSale" }],
  "schools": { "elementarySchool": { "name": "Bluebonnet Trail", "district": "Manor ISD" } }
}

错误与失败路径

你的客户端几乎不会从工具调用中看到 HTTP 错误码。MCP 层返回 200，并将失败信息放入结果中，同时将 isError 设为 true，失败原因以文本形式给出。代理会读取一条消息，而不是你可能预期的状态行。

密钥错误会以工具输出的形式呈现，而不是连接失败。tools/list 接受任何非空密钥并返回两个工具，因此客户端会完成握手并显示正常。然后，第一次工具调用会返回 isError: true，文本为 HasData API error: 401 Unauthorized。请注意这个字符串，因为流程中不会有更早的环节报告这个问题。

**缺少密钥是唯一的真实 HTTP 错误。**授权在任何工具调用之前进行，连接本身会以 401 失败。CORS 响应头存在，浏览器客户端会读取状态码，而不是不透明的网络错误。

会破坏工具代码验证的参数会在抓取前被拒绝。 服务器以 isError: true 和文本 MCP error -32602: Input validation error 响应，并指出违规字段。不会发起抓取，也不会扣费。

无匹配结果的搜索会返回一个成功的响应，其中 properties 数组为空，不会返回错误。即使是没有符合条件的组合，返回的 requestMetadata.status 也仍为 ok 状态。在遍历之前请先检查数组长度。

已下架的房源会返回 400，且 requestMetadata.status 为 error。旧搜索结果中的 URL 可能指向一个已不存在的房源。

携带数据的响应还会包含 requestMetadata.id，在寻求支持时值得引用。

定价、免费额度与限制

每个 Zillow 工具每次成功调用消耗 5 点积分。如果启用了 extractAgentEmails，房产详情调用会再增加 5 点积分，变为 10 点而不是 5 点，因此除非需要邮箱，否则请保持关闭。响应大小不会影响价格。

免费试用额度为 1,000 点积分，30 天有效，无需绑定银行卡，按基础费率可使用 200 次 Zillow 调用。之后，有效帐户只要每日结余低于 100，就会自动每日补入 100 点积分，因此一个低流量的代理可以无限期地运行在免费额度上。

付费套餐从 每月 49 美元 起，包含 200,000 个积分，也就是 40,000 次调用。单价会随用量增加而下降，从入门包的每 1,000 次调用 1.23 美元，到 Business 的 0.50 美元、Growth 的 0.42 美元，再到最大 高用量套餐 上的 0.37 美元。

你的套餐还决定了并发数。免费试用允许同时 1 个请求，Startup 为 15，Business 为 30，Growth 为 50，高用量套餐则是 200 到 1,500。任何无人值守的自动化程序都应对溢出情况做防御性处理。

返回非 200 的请求不计费。一次调用成功但没有找到任何结果，仍然算一次调用编码。

工具选择

apis 查询参数决定你的 agent 能使用哪些工具。工具越少，定义工具就会占用的上下文越少，模型选错工具的机会也更少。

?apis=zillow                     the two tools in this repo
?apis=zillow,redfin              add Redfin real estate
?apis=zillow,google_maps         add Google Maps places

该参数接收 provider 名称（如 zillow）和单个 API 名称（如 zillow_listing）。拼写错误的名称会被忽略。如果所有名称都无效，请求会返回 400，响应体会同时列出它识别不出的值和所有有效值。去掉该参数，同一个端点就会暴露 HasData 的全部 57 个工具。

对比

Zillow 自己的 API 只面向需要管理自有或 MLS 库存的会员和合作方，比如 Bridge Interactive 和 Mortgage APIs，并不是一种自助读取公开市场的方式。要搜索挂牌并读取任意房源，抓取公开页面才是办法，而这个服务器就是通过稳定 schema 在后台完成这一点的。

这个服务器不做什么。 不发布内容、不提交销售线索、不处理账户数据。它只读取未登录访问者能在 Zillow.com 上看到的内容。

常见问题

有官方 Zillow MCP 服务器吗？

Zillow 没有发布过官方服务器。这个服务器由 HasData 维护，读取的是公开页面，所以不需要 Zillow 账户。

什么是 Zillow MCP 服务器？

就是一个把 Zillow 挂牌数据封装成工具、供 AI 客户端调用的服务器。客户端通过 Model Context Protocol 发送工具调用，服务器取回数据并返回结构化 JSON，模型再基于结果工作。本服务器对外提供两个工具，并以远程方式运行。

我需要 Zilloow 账户或 API key 吗？

不需要。唯一需要的凭据是你的 HasData key。无需申请任何 Zillow 会员资格，因为这些工具读取的是公开的 Zilloow.com 页面。

为什么搜索结果里没有价格历史或学校信息？

因为 Zillow 不会把它们放进搜索卡。这些信息位于房源详情页，详情工具会通过 URL 读取该页面。先用搜索筛选出关注房源，再用房源工具获取更完整的信息。

價格预估是什么意思？

zestimate 对象包含 Zillow 自己的估算价值、其上下区间和一个租金估算值。这是模型输出，既不是正式评估，也不是成交价。应把它当作一个估算值。

我可以把它和 HasData 的其他 API 化在一起用吗？

可以。apis 参数接收一个列表，?apis=zillow,redfin 会让你的 agent 同时拥有 Zillow 和 Redfin 的能力。去掉该参数 可以得到全部工具。

HasData 和 Zillow 是关联方吗？

不是。HasData 是独立服务，后与 Zillow Group, Inc. 无关联，也未得到 背书。Zillow 是各自所有者的商标。

合规与个人数据

HasData 只访问公开可获取的数据。平台条款可能限制自动化访问，你需要 自行承担合规责任。当收集的数据包含个人信息时，例如挂牌经纪人联系表，请确保在 GDPR、CCPA 或您所管辖区域的等效规则下拥有合法依据。

HasData 链接

开发

这是一个远程服务器的配置加文档仓库。连接开发步骤，也没有任何需要容器化的东西。

test/ 里的测试是对工具契约的验证，正好是最容易在没有提交的情况下出错的部分。它们会确认 ?apis=zillow 恰好返回两个工具，每个工具都声明了必要的参数，名称没变，同时在用的 key 确实有效。最后一次检查会真正调用一个工具并消耗 5 个积分，等于“金丝雀”的价格，能在正确的时机报出失败。

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

同一套测试会在每次推入推送时和每周定时在 CI 中运行，原因在于上游工具列表可能在没有人改动这个仓库的情况下发生变化。失败意味着工具列表移动了、key 失效了，或者端点无法访问，断言消息会明确指出属于哪种情况。

参与贡献

最有用的贡献是修正工具表和响应示例，因为这些部分最容易偏移。请附上你实际发起的调用和实际响应。来自 fork 的 Pull Request 会在没有 key 的状态下运行测试套件，实时检查会改为跳过错误，而不是搞出红色失败。

许可

MIT，请参见 LICENSE。