compass-mcp

compass-mcp

面向 Claude 的 Compass 房地产 MCP 服务——通过自然语言搜索房源、获取房产详情、照片图库、价格历史记录，以及进行负担能力和抵押贷款计算。

⚠️ Compass 不提供公开的消费者 API。此服务会抓取 compass.com 自行发送到浏览器的同一份服务端渲染 HTML，并通过 ContextMint Bridge 扩展，经由你已登录的浏览器标签页转发。每个请求都会使用你现有的会话执行——你的 Cookie、TLS 和 JS 上下文——就像你亲自在浏览器中点击一样。请将此视为对 Compass 网站的非正式使用。使用风险自负。

工具

工具	用途	受身份验证范围限制
compass_search_properties	按地点、价格区间、卧室数量和房屋类型搜索房源。将自由文本转换为 Compass 的 URL 路由格式，并提取 SSR 房源数组。
compass_get_property	根据 URL 或 listing_id_sha 获取房产的完整记录。包括地址、社区、卧室/浴室数量、平方英尺、地块、价格和每平方英尺价格、月费、MLS 状态、设施、学校和地块编号。
compass_get_property_photos	完整照片图库——listing.media[] 中的每张图片都包含原图和缩略图 URL 及像素尺寸。楼层平面图和其他媒体需通过 include_all_categories 才能获取。
compass_get_price_history	完整的房源历史事件（挂牌/售出/待售/价格变更/下架），包括日期、价格、状态和 MLS 归属信息。返回当前房源和过往房源的汇总数据。
compass_compare_properties	并排比较最多 25 套房产，并可选择生成对齐的摘要表。逐行记录每个目标的错误。并发获取。
compass_calculate_affordability	本地负担能力计算器——根据收入、DTI 和利率计算最高购买价格。无需网络。
compass_get_by_address	一次调用即可将自由文本街道地址解析为规范的 Compass URL、listing_id_sha 和 pid。找不到匹配项时返回 { resolved: false, error: "no listing found" }，而不会抛出错误。
compass_resolve_addresses	compass_get_by_address 的批量版本：使用相同的逐级解析器，在一次调用中解析多个地址，并按行返回错误。
compass_bulk_get	一次调用即可通过 URL 或 listing_id_sha 获取最多 200 个房源。每个目标对应一行；逐行记录每个目标的错误。
compass_get_comparable_rentals	搜索房产附近的出租房源，范围限于目标房产所在的城市/州/ZIP。
compass_get_agent_listings	获取 Compass 经纪人的活跃房源（使用 include_closed 获取已成交房源）。
compass_calculate_mortgage	本地 PITI 计算器——本金和利息、税费、保险、HOA、PMI。无需网络。
compass_get_saved_homes	尚未支持——Compass 通过身份验证范围内的 GraphQL 渲染 /overview/favorites，我们尚未识别该接口。调用会抛出明确的“尚未接入”错误。	✓
compass_get_saved_searches	尚未支持——与已保存房产的情况相同。	✓
compass_healthcheck	通过桥接发送一个无操作请求并往返验证，以确认 WebSocket 桥接、扩展和已登录的 compass.com 标签页均有响应。
compass_register_session	注册或刷新一个以账户身份为键的逻辑会话（本地；无需网络）。
compass_set_active_session	切换用于响应后续请求的已注册会话（本地）。
compass_get_session_context	列出已注册的会话和当前活动会话（本地）。

响应大小

列表读取工具接受可选的 view 参数："compact"（默认值）或 "full"。Compact 会移除图片和头像 URL（包括 primary_photo_url / primary_thumbnail_url），并保留其他所有字段；view: "full" 会原样返回包含这些 URL 的负载。

接受 view 参数的工具：compass_search_properties、compass_get_property、compass_bulk_get、compass_compare_properties、compass_get_price_history、compass_get_comparable_rentals、compass_get_agent_listings、compass_get_by_address。

1.1.9 版本变更： compass_get_property、compass_bulk_get、compass_compare_properties、compass_get_price_history 和 compass_get_comparable_rentals 过去会返回所有字段，包括媒体 URL。现在，它们和其他读取工具一样，默认使用 compact 模式。如果你依赖这些工具返回照片或头像 URL，请传入 view: "full"，或使用 compass_get_property_photos 获取图库。

compass_get_property_photos 不接受 view 参数——该工具的用途就是获取图库 URL，因此它始终会返回这些 URL。

使用条款确认

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

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

2. Compass 使用条款适用于你对本服务的使用，就像这些条款适用于你直接使用 compass.com 一样。与此最相关的条款如下：

除非事先获得适用的 Compass 公司明确书面许可，否则不得出于任何目的，或通过任何方式，对服务进行自动化抓取或查询（包括但不限于屏幕和数据库抓取、蜘蛛程序、机器人、爬虫，以及任何旨在从服务获取信息的其他自动化活动）。

以及：“你同意对密码保密，不使用他人的账户，也不允许他人使用你的账户。”

每次调用此服务中的工具，即表示你同意这些条款——维护者于 2026-05-23 阅读了这些条款。Compass 的条款禁止未经书面许可进行自动化抓取，IDX 房源数据仅授权用于个人非商业用途。

3. 仅限个人非商业用途。 本项目与 Compass, Inc. 无关联，也未获其认可或赞助，亦非与其合作开发。它是一款个人自动化工具，用于读取 compass.com 自行发送到浏览器的相同服务端渲染 HTML。请勿用它批量提取房源、重新分发 IDX 数据、训练 AI 模型、填充竞争性的房地产产品，或用于任何商业目的。

4. 不保证稳定性。 此服务会读取私有的内联脚本状态（global.uc.sharedReactAppProps、window.__INITIAL_DATA__.props.listingRelation.listing）和 SSR URL 约定（/homes-for-sale/<slug>/、/homedetails/<slug>/<id>_lid/），Compass 可能会在不另行通知的情况下更改这些内容。此服务可能会出错，也可能停止工作。这是有意为之——这些接口并非由 Compass 提供维护支持。

5. 你需对使用此服务访问 Compass 所产生的任何后果承担全部责任——包括限速、账户停用、IP 封锁、AWS WAF 验证挑战，或 Compass 采取的任何执法措施。如果 Compass 对你的使用提出异议，请停止使用此服务。

本节是维护者出于善意对条款所作的摘要——不构成法律建议，也不会修改或取代 Compass 的实际使用条款。

安装

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

添加到 .mcp.json：

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

选项 B — 从源代码安装

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

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

一次性浏览器设置

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

• Chrome： 下载 Chrome zip 文件，解压，然后依次点击 chrome://extensions → 切换开发者模式 → 加载已解压的扩展程序 → 选择解压后的文件夹。
• Safari： Bridge 已内置于 ContextMint 应用中；你可以在 Safari 的设置中启用它。ContextMint 应用尚未公开提供下载，因此目前没有 Safari 安装链接——暂时请使用 Chrome。

来源。 ContextMint Bridge 是更名后的 fetchproxy 浏览器扩展，由同一位维护者开发——fetchproxy 自己的 README（扩展）指向了它。其源代码公开于 nullnet-app/contextmint-bridge：你可以自行构建（其 README 介绍了 npm run build），也可以将发布的 zip 文件与其旁边发布的 .sha256 文件进行校验：

shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256

打开 compass.com 并登录。这就是此服务所需的全部身份验证。

工作原理

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

MCP 服务在 Node 中运行，但所有发往 compass.com 的 HTTP 调用都会通过 ContextMint Bridge 扩展分发到你当前打开的浏览器标签页中。每个请求都使用你现有的会话——TLS 指纹、Cookie 和 JS 执行上下文都与当前显示的页面一致。没有无头浏览器替身，没有单独的身份，也没有第三方代理：只有你的真实浏览器代表自身执行操作，MCP 服务则负责选择要请求的内容。

Compass 的页面采用 SSR React，且没有公开的 JSON API——每个工具都会从内联脚本全局变量中提取数据（搜索页面上的 global.uc.sharedReactAppProps，以及 homedetails 页面上的 window.__INITIAL_DATA__.props.listingRelation.listing）。客户端会将这些数据封装到工具接口中，因此调用者无需自行解析 HTML。

命令

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