ARV Estimator

arv-mcp

一个 MCP 服务，可根据附近已售房源的可比案例估算房屋的 修缮后价值（ARV），并向模型提供估值依据及评分结果，以便模型解释、核查和质疑估值。

询问 Claude “1234 Main St 的 ARV 是多少？”，即可获得典型 估值、翻新后的估值区间、置信度等级、支持该估值的可比案例（以及被剔除的案例和原因）、目前附近在售的房源，以及任何应当谨慎对待的警告。

You:    What's the ARV of 1234 Main Street?

Claude: Typical value is about $516k ($263/sqft on 1,961 sqft), based on
        20 eligible sales, 5+ of them within a quarter mile (confidence 5/5).
        Renovated comps support $541k–$586k. The closest match, 1260 Main
        Street, sold 23 days ago for $465k ($272/sqft): same subdivision,
        a bit smaller, no pool.

        Worth knowing: this house itself sold this week for $432,500
        ($220/sqft), well under the comp-based value. That usually means it
        sold in rough condition, which fits a flip at the renovated range.
        Two of the eligible comps were distressed sales; without them the
        median barely moves.

这不是评估报告。 数据来自 Realtor.com 上的公开房源信息，由 HomeHarvest 提供，可能有误或缺失。请将其用于调研并作为起点，而非用于贷款或法律决策。

工作原理

address ──► verify the property ──► sold comps ──► score & gate ──► estimate
               │  (any status)        within 1.5 mi    each comp       + evidence
               └─ not verified? ──► locate it + ask for its facts

1. 查找目标房屋。 根据地址解析 Realtor.com 中对应的房源记录，地址必须与街道和单元完全匹配，无论房屋处于待售、待成交、已售还是非市场状态。Realtor.com 的地理编码器很容易因地址不准确而返回错误房屋，因此系统会根据输入的街道和单元核查每个结果。如果无法验证，会定位地址（使用 Census 地理编码器或调用方提供的纬度／经度），并要求提供所需信息（sqft、property_type），而不是自行猜测。

2. 获取目标房屋坐标附近的可比案例： 搜索过去 180 天内、1.5 英里范围内的已售房屋（两项均可针对每次调用调整），面积在目标房屋的 ±40% 范围内，且房屋类型相同。目标房屋自身的售出记录会单独提取并报告，因此刚售出的房屋不会与自身比较。

3. 根据 13 项因素为每个可比案例评分： 面积、建造年份、地块、卧室／浴室数量、房屋类型、近期程度、状况信号、距离、社区、车库、楼层数、泳池和地下室。每项已知因素还有一个门槛。只要有一项不达标（房屋类型不同、面积大得多、建造时间相差数十年），无论其他方面多么匹配，都会直接剔除该案例。面积、房龄和地块门槛会针对紧邻的案例放宽，并随距离增加而收紧。

4. 检查微型市场。 每个可比案例所在社区的中位价（或其每平方英尺价格）必须处于目标房屋当地价格水平的 ±20% 范围内，以免价格较高区域中物理条件高度匹配的房屋抬高估值。社区信息来自 MLS 的 “Subdivision” 字段，并会合并 “Unit 2” 或 “Ph 04 Sec 01” 等分期名称。

5. 估算：

   • 典型估值： 相似度加权的每平方英尺价格中位数 × 目标房屋面积。
   • 翻新后估值区间： 加权第 75 至第 90 百分位数，即可比案例池中表现最好的部分所支持的范围。
   • 置信度 1–5： 支持估值的可比案例有多接近。

   如果没有可比案例通过筛选，工具会退回使用该地区的常见价格，并明确说明该估值没有可比案例作为依据。

工具

get_arv

参数	描述
address（必填）	完整街道地址，包括单元号。
sqft、property_type	覆盖房源记录中的信息。无法验证地址时必填。
beds、baths、year_built、lot_sqft、stories、garage、has_pool	覆盖或补充房屋信息；也可用于假设分析（例如“如果有泳池会怎样？”）。
latitude、longitude	为地理编码器无法找到的房屋指定位置。
radius_mi、days_back	可比案例搜索范围：0.25–5 英里（默认 1.5）、30–730 天（默认 180）。
include_market_context	同时获取附近在售／待成交的房源（默认 true）。
max_comps	返回符合条件的可比案例数，1–25（默认 10）。

返回 subject、estimate（arv、renovated_range、arv_fallback、 时间范围）、confidence、pool_stats、eligible_comps（每项包含扣分因素 和任何房屋困境标记）、excluded_comps（包含剔除原因）、market_context 和 guidance。未知信息为 null，绝不会是 0。

对比房源地图

在支持 MCP Apps 的宿主中 （例如网页版和桌面版 Claude），get_arv 还会在答案旁打开一张交互式地图：

• 用橙色房屋图钉标出目标房产
• 已售对比房源显示为价格标签：为估价提供依据的房源使用绿色 ⭐，其余使用蓝色
• 在售和待售房源显示为青绿色 🏠 和紫色 ⏳ 标签；符合对比房源条件时会带有 ⭐
• 点击每个标签会弹出房源信息；对于未采用的对比房源，还会显示未采用的原因
• 街道／卫星底图、“售出时间范围”筛选器（3M、6M、1Y、All），以及在售／待售房源图层切换开关

地图通过仅供应用使用的工具 get_comp_map 获取数据，模型看不到该工具。打开地图时会复用 get_arv 的缓存数据，因此不会产生额外请求。不支持 MCP Apps 的客户端只会收到常规的 get_arv 结果。

lookup_property

地址的已核实记录：面积、卧室／浴室数量、建成年份、地块、楼层数、车库、泳池、分区、状态、挂牌价（仅在房源挂牌期间提供）和上次成交信息。

提示词：analyze_arv

以评估师的方式逐步分析（目标房产 → 对比房源 → 调整 → 估价范围）。 在 Claude Code 中会显示为斜杠命令。

错误

失败时会返回 {"error": {"code", "message", ...}}，以便模型采取相应操作：

代码	含义
ADDRESS_NOT_VERIFIED	已找到地址，但没有匹配记录；needs 会列出需要询问的房源信息。
ADDRESS_NOT_FOUND	无法找到该地址。
MISSING_FACTS	记录缺少估价所需的信息（例如平方英尺数）。
UNSUPPORTED_PROPERTY_TYPE	空置土地：没有可按平方英尺计价的居住面积。
NO_COMPS	指定时间范围内没有成交记录；请尝试增大 radius_mi／days_back。
RATE_LIMITED	触发本地速率限制；retry_after_s 会告知何时重试。
UPSTREAM_ERROR	Realtor.com 拒绝了请求，或请求失败。

安装

Claude Desktop：一键安装（推荐）

1. 从最新版本下载 arv-mcp.mcpb。
2. 双击该文件，或将其拖入 Claude Desktop 的 设置 → 扩展，然后点击 安装。

就这么简单：无需终端、配置文件，也无需安装其他内容。Claude Desktop 会自行设置 Python 和依赖项；首次启动时会进行设置，约需半分钟。

开发者

需要 Python 3.11+。已发布到 PyPI，并以 io.github.mariov7757/arv-mcp 列入 MCP Registry。

Claude Code

claude mcp add arv-mcp -- uvx arv-mcp

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "arv-mcp": {
      "command": "uvx",
      "args": ["arv-mcp"]
    }
  }
}

pip

pip install arv-mcp

若要运行尚未发布的 main 分支，请使用 uvx --from git+https://github.com/mariov7757/arv-mcp arv-mcp。

从克隆的仓库安装

git clone https://github.com/mariov7757/arv-mcp && cd arv-mcp
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
claude mcp add arv-mcp -- "$PWD/.venv/bin/arv-mcp"

Windows：如果 uvx 安装 pywin32 失败（os error 32／ “被另一个进程使用”，通常是因为杀毒软件正在扫描 uv 的临时构建文件夹），请改为安装到常规虚拟环境中，并让 客户端指向已安装的可执行文件：

uv venv $HOME\.arv-mcp
uv pip install --python $HOME\.arv-mcp\Scripts\python.exe arv-mcp
claude mcp add arv-mcp -- $HOME\.arv-mcp\Scripts\arv-mcp.exe

配置

所有配置项均为可选，通过环境变量设置：

变量	默认值
ARV_MCP_REQUESTS_PER_MIN	30	Realtor.com 每分钟请求数（令牌桶）……
ARV_MCP_REQUEST_BURST	10	……以及可同时发出的请求数。
ARV_MCP_GEOCODER_PER_SEC	1	Census 地理编码器每秒请求数。
ARV_MCP_RATE_WAIT_S	15	调用等待速率限制时隙的最长时间，超时后返回 RATE_LIMITED。
ARV_MCP_MAX_CONCURRENT	2	同时处理的工具调用数。
ARV_MCP_LOG_LEVEL	WARNING	日志输出到 stderr。

一次完整的 get_arv 会向 Realtor.com 发出 5 个请求（2 个用于查询目标房产， 1 个用于查询已售对比房源，2 个用于查询在售／待售房源），耗时约 4–6 秒。结果会缓存 15 分钟，因此对同一地址的后续查询和假设分析都能即时返回。

局限性

• 针对 Phoenix 都会区调优。 门槛区间和置信度等级基于约 8,000 个 Phoenix 地区的估值进行校准。引擎可在美国任何地方运行，但在其他市场（尤其是乡村地区或交易量较低的市场），应多参考可比房源和置信度等级，并扩大 radius_mi / days_back。
• 典型价值未考虑房屋状况。 系统会标记问题房产销售（MLS REO/short-sale 状况、“fixer”/“as-is”措辞），并报告其对中位数的影响，但不会将其排除。
• $/sqft 不适用于某些房产。 系统会拒绝估算土地；对于农场、多户住宅和移动房屋，则会发出警告。
• 非官方数据源。 HomeHarvest 会抓取 Realtor.com 的公开网站。请求通过你自己的设备发出，并受到速率限制，但网站随时可能变更或阻止访问。homeharvest 固定在经过测试的版本范围内，因为客户端依赖其内部实现。

开发

pip install -e ".[dev]"
pytest            # offline suite; real network calls are blocked
ARV_MCP_LIVE_ADDRESS="<a real address>" pytest -m live   # smoke tests against Realtor.com + Census
ruff check src tests

src/arv_mcp/
  server.py         MCP tools, instructions and prompt
  service.py        address in, estimate + evidence out
  arv.py            eligibility, weighted median, renovated range, confidence
  scoring.py        per-comp gated scoring
  comps.py          comp normalization and bad-data filters
  ratelimit.py      token buckets
  data/client.py    Realtor.com transport over HomeHarvest
  data/homeharvest.py  subject lookup, comp searches, field extraction
  data/geocode.py   Census geocoder

发布

版本号仅在一处定义：src/arv_mcp/__init__.py 中的 __version__。

1. 更新 __version__（修复问题时递增补丁版本，新增工具、参数或字段时递增次版本），并在 CI 通过后合并到 main。

2. 为发布打标签并推送标签：

   git tag v0.2.0
   git push origin v0.2.0
   

随后，发布工作流会：

• 检查标签是否与 __version__ 一致
• 运行 lint 和测试，并构建软件包
• 使用 Trusted Publishing 发布到 PyPI（无需 API 令牌）
• 将版本写入 server.json，并将其发布到 MCP Registry，名称为 io.github.mariov7757/arv-mcp，通过 GitHub OIDC 进行身份验证
• 构建 Claude Desktop 扩展（arv-mcp.mcpb，参见 scripts/build_mcpb.py），使用官方 mcpb CLI 验证，并将其附加到 GitHub Release

要在本地构建扩展（需要 uv）： python scripts/build_mcpb.py，生成 dist/arv-mcp.mcpb。

PyPI 上的版本号永久有效。出现问题的版本会在 PyPI 上撤回，并由下一个补丁版本替代；版本号绝不会重复使用。

许可证

MIT