homes-mcp

homes-mcp

将 homes.com 房地产服务接入 MCP 服务，供 Claude 使用——通过自然语言搜索房源、解析地址、获取房产详情、价格／税费历史记录、市场报告、已保存的房源、照片集，以及进行可负担性／抵押贷款计算。

⚠️ homes.com 未发布面向消费者的公共 API。此服务会读取 homes.com 自身发送到浏览器的相同服务端渲染 HTML 和 Schema.org JSON-LD，并通过 ContextMint Bridge 浏览器扩展，经由你已登录的浏览器标签页进行访问。每个请求都会使用你现有的会话——你的 Cookie、TLS 和 JS 上下文——就像你亲自在浏览器中点击一样。请将此视为对 homes.com 的非正式使用。使用风险由你自行承担。

工具

工具	用途
homes_search_properties	按自由文本位置（城市/邮编/社区）搜索房源。将输入转换为适用于 homes.com URL 路由的 slug（位置为空或无法转换为 slug 时会报错，而不是返回空结果），并解析 JSON-LD CollectionPage.mainEntity.itemListElement[]。可按 property_type、listing_type、sort 和 price_min/price_max 价格区间筛选。返回地址、价格、卧室/浴室数量、平方英尺、主照片、经纪人 + 经纪公司；超过约 40 条房源的 SSR 上限时会标记 truncated/total_estimated。
homes_get_by_address	将一个美国街道地址解析为 homes.com 上对应的规范房产 URL + 不透明哈希。依次尝试结构化输入提示 → slug → 城市/邮编搜索回退，并验证完整街道名称和单元号。返回 matched_via；无法解析时返回 { resolved: false }。
homes_resolve_addresses	批量调用 homes_get_by_address（最多 100 个地址，保留输入顺序，逐行返回结果）。批量处理 3 个或更多地址时优先使用。
homes_get_property	按 URL 获取房产的完整记录。解析 JSON-LD + DOM 侧的各个部分：地址、纬度/经度、卧室/浴室数量、平方英尺、建造年份、价格、状态、经纪人（姓名/职务/个人资料；仅当 include_agent_contact: true 时包含电话/电子邮件）+ 经纪公司、亮点、学校、HOA（原始值 + 月费）、土地面积（平方英尺 + 英亩）、停车位、供暖/制冷、MLS ID/来源、税费、上市天数、降价记录、extracted_features。可选内嵌 price_history/tax_history。
homes_get_property_photos	从详情页的 <img> 标签抓取完整照片库（JSON-LD 仅包含一张图片）。每张照片返回 { url, position, alt? }，并筛选出 homes.com CDN 中的照片。
homes_bulk_get	单次调用获取最多 200 套房产的结构化记录（逐行返回错误，保留输入顺序）。
homes_compare_properties	并排比较 2–8 套房产，并提供对齐的摘要表。逐行记录每个目标的错误。并发获取数据。
homes_get_nearby_listings	获取详情页中“此房产附近待售房源”交叉链接卡片（待售房源，可选租赁房源）。仅返回 URL + 地址。
homes_get_history	单次获取价格 + 税费历史：listing_events、ownership_events、lien_events、标准化后的 events_normalized 和 tax_records。events_normalized 仅在 PriceChange 行设置 price_change_pct；其他行包含 homes.com 的“挂牌价到成交价”数值 list_to_sale_pct（不含 dom / source_mls 键）。
homes_get_property_history	已弃用 — 仅提供价格/所有权/留置权时间线。请优先使用 homes_get_history。
homes_get_tax_history	已弃用 — 仅提供逐年税费记录。请优先使用 homes_get_history。
homes_get_market_report	根据市场的中位数/平均值/每平方英尺价格，数据取自 sold 搜索页面的 JSON-LD。位置为空或无法转换为 slug 时会报错，而不是返回空市场结果。
homes_get_saved_homes	获取已登录用户收藏的房产。需要通过身份验证。
homes_get_saved_searches	获取已登录用户保存的搜索。需要通过身份验证。
homes_calculate_affordability	本地负担能力计算器 — 根据收入 + DTI + 利率计算最高购房价格。不访问网络。
homes_calculate_mortgage	本地 PITI 计算器 — 计算本金 + 利息、税费、保险、HOA、PMI。不访问网络。
homes_estimate_rent_vs_buy	本地租房与买房模型 — 需提供 monthly_rent（homes.com 没有可用于推算该值的租金信号；见下文）。不访问网络。
homes_healthcheck	通过 fetchproxy 桥接层对 /robots.txt 执行往返请求（使用来自 @chrischall/mcp-utils/fetchproxy 的共享 registerBridgeHealthcheckTool），并返回诊断信息：桥接层角色/端口/版本、扩展连接状态（bridge.session_state、pending_pair_code、extension_connected）、分类后的 error.kind（timeout / bridge_down / session_not_ready / protocol / unknown），以及通俗易懂的提示，用于区分“桥接层已关闭”、“扩展未连接/配对码待处理”和“homes.com 侧问题”。
homes_get_session_context / homes_register_session / homes_set_active_session	列出/注册/切换账户 标签，供你自行记录管理。仅设置标签：请求始终使用 fetchproxy 浏览器标签页当前登录的账户。

已知数据缺口：租金估算

homes.com 不会在其面向消费者的网站上发布任何租金估算——没有 rent_zestimate 的对应数据，也没有房产详情页上的“预估租金”组件，更没有可比租赁房源的接口。homes_estimate_rent_vs_buy 工具可用于计算，但调用方必须直接传入 monthly_rent（无法从 homes.com 获取租金估算后再传入）。

如需租赁相关信息，请使用配套 MCP：zillow_get_property 的详情记录中包含 rent_zestimate，而 redfin_get_comparable_rentals 可根据 URL 返回租赁可比房源。可参阅 issue #28 了解可行性调查。

条款确认

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

1. 此服务会访问你自己的 homes.com 会话。 每个请求都会通过 ContextMint Bridge 扩展，经由你自己的浏览器标签页发送——使用你的 Cookie、你的 TLS 和你的会话。它不会、也无法访问其他人的账户。

2. homes.com 的使用条款适用于你对本服务的使用，就像适用于你直接使用 homes.com 一样。条款禁止未经书面许可进行自动化爬取，IDX 房源数据仅授权用于个人非商业用途。每次调用此服务中的工具，即表示你同意这些条款。

3. 仅限个人非商业用途。 本项目与 homes.com 或 CoStar Group 无关联，也未获其认可、赞助或与其合作。这是一款个人自动化工具，用于读取 homes.com 发送到你浏览器的相同服务器渲染 HTML 和 Schema.org JSON-LD。请勿用它批量提取房源、再分发 IDX 数据、训练 AI 模型、填充竞争性房地产产品，或用于任何商业目的。

4. 不保证稳定性。 此服务会读取 SSR 页面的 Schema.org JSON-LD（<script type="application/ld+json">）和 DOM 端的 <img> 标签；这些页面的 URL 规则（/<city>-<state>/、/property/<slug>/<id>/）可能在不另行通知的情况下更改。服务可能会出错，也可能停止工作。这是设计使然——相关页面并非由 homes.com 维护。

5. 你须对将此服务与你访问 homes.com 相关联所产生的任何后果承担全部责任，包括速率限制、账户停用、IP 封禁、AWS WAF 验证挑战，或 homes.com 采取的任何执法措施。如果 homes.com 对你的使用提出异议，请停止使用此服务。

本节是维护者本着诚信对条款所作的摘要，不构成法律建议，也不会修改或取代 homes.com 的实际使用条款。

安装

选项 A — npx（首次发布后）

添加到 .mcp.json：

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

选项 B — 从源代码安装

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

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

一次性浏览器设置

homes-mcp 通过 ContextMint Bridge 扩展与浏览器通信。该扩展由所有基于 fetchproxy 的 MCP（zillow-mcp、opentable-mcp、resy-mcp、……）共享，并需单独安装——此处不包含该扩展。请从 ContextMint Bridge releases 获取：

• **Chrome：**下载 Chrome 压缩包并解压，然后打开 chrome://extensions → 切换到开发者模式 → 加载已解压的扩展程序 → 选择解压后的文件夹。
• **Safari：**目前尚不可用——该扩展将内置于 ContextMint 应用中，但目前没有公开下载链接。暂时请使用 Chrome。

来源。 ContextMint Bridge 是 fetchproxy 浏览器扩展的新名称，由同一位维护者开发；fetchproxy 自己的 README（扩展）中也指向了它。其源代码公开于 nullnet-app/contextmint-bridge：你可以自行构建，也可以根据旁边发布的 .sha256 文件校验发布压缩包（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。目前还没有 Chrome 网上应用店页面。

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

工作原理

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

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

homes.com 的页面是 SSR React，且没有公开的 JSON API——每个工具都会从各页面内嵌的 Schema.org JSON-LD 区块（<script type="application/ld+json">）中提取数据。搜索页面会将房源放在 CollectionPage.mainEntity.itemListElement[] 中；详情页面会输出一个 RealEstateListing 图节点，其中 mainEntity 包含地址、面积和地理位置，offers.offeredBy[] 则包含房源经纪人。由于 JSON-LD 只包含一张主图，照片会从 DOM 中抓取。客户端会将这些内容封装为工具接口，因此调用方无需自行解析 HTML。

命令

npm test               # tsc typecheck + 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