ARV Estimator

arv-mcp

近隣の成約事例から住宅の**修繕後価値（ARV）**を推定し、その数値の根拠となるスコア付きの証拠をモデルに提供することで、モデルが説明、確認、検証できるようにするMCPサーバーです。

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.

不動産鑑定ではありません。 データはHomeHarvest経由でRealtor.comの公開物件情報から取得しており、誤りや欠落がある場合があります。調査や判断の出発点として使用し、融資や法的判断には使用しないでください。

仕組み

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のジオコーダーは、住所が正しくないと別の住宅を返すことがあるため、すべての結果を入力された番地と部屋番号に照らして確認します。一致が確認できない場合は、住所を特定（国勢調査局のジオコーダー、または呼び出し元から提供された緯度・経度を使用）し、推測する代わりに必要な情報（sqft、property_type）をツールが尋ねます。
2. 対象物件の座標周辺から成約事例を取得します。 過去180日以内、半径1.5マイル以内（どちらも呼び出しごとに調整可能）で、対象物件と同じ物件種別、サイズが±40％以内の物件を取得します。対象物件自身の売買履歴は除外して別途報告するため、売れたばかりの住宅が自分自身の比較対象になることはありません。
3. 各成約事例を13項目で評価します。 サイズ、築年、敷地、寝室・浴室数、物件種別、成約時期、状態を示す情報、距離、分譲地、車庫、階数、プール、地下室を評価します。既知の各項目には最低基準も設けています。いずれか1つでも基準を満たさない事例（物件種別が異なる、住宅が大幅に大きい、築年が数十年離れているなど）は、ほかの項目がどれほど優れていても除外します。サイズ、築年、敷地の基準は、隣接する事例では緩和され、距離が離れるほど厳しくなります。
4. 周辺の小規模市場を確認します。 各成約事例が属する分譲地の中央値（またはその物件自体の平方フィート当たり価格）が、対象物件の地域の価格水準の±20％以内に収まる必要があります。これにより、物理的な条件がよく一致していても、より高価な地域の事例によって推定額が引き上げられるのを防ぎます。分譲地の情報はMLSの「Subdivision」フィールドから取得し、「Unit 2」や「Ph 04 Sec 01」などの区画はまとめて扱います。
5. 推定します。
   • 標準的な価格： 類似度で重み付けした平方フィート当たり価格の中央値 × 対象物件の平方フィート数。
   • リノベーション後の価格帯： 重み付けした75～90パーセンタイル。比較対象の上位物件が裏付ける価格帯です。
   • 信頼度1～5： 根拠となる成約事例がどれだけ近いかを示します。

成約事例が1件も残らない場合、ツールは地域の一般的な価格水準を使い、推定額が成約事例に裏付けられていないことを明示します。

ツール

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を返します。不明な情報は0ではなくnullになります。

比較対象の地図

MCP Apps に対応するホスト（Web版およびデスクトップ版の 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 と依存関係を自動でセットアップします。初回起動時は処理に約 30 秒かかります。

開発者向け

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	1 分あたりの Realtor.com リクエスト数（トークンバケット）…
ARV_MCP_REQUEST_BURST	10	…および一度に実行できるリクエスト数。
ARV_MCP_GEOCODER_PER_SEC	1	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 都市圏向けに調整されています。 判定基準と信頼度の段階は、Phoenix 周辺の約8,000件の評価額をもとに 調整されています。エンジンは米国内のどこでも動作しますが、他の市場（特に地方や取引量の少ない市場）では、比較物件と信頼度の段階を 重視し、radius_mi / days_back の範囲を広げてください。
• 標準価格は物件の状態を考慮しません。 問題のある販売物件にはフラグが付けられ （MLS の REO／ショートセール条件、「fixer」／「as-is」の表記）、中央値への 影響が報告されますが、対象からは除外されません。
• 一部の物件では、平方フィートあたりの価格は適切な指標ではありません。 土地は対象外です。農場、 集合住宅、モバイルホームには警告が表示されます。
• 非公式のデータソースです。 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

リリース

バージョンは1か所で管理されています。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（API トークン不要）を使って PyPI に公開します
• バージョンを server.json に記録し、GitHub OIDC 認証を使って MCP Registry に io.github.mariov7757/arv-mcp として公開します
• Claude Desktop 拡張機能（arv-mcp.mcpb。詳細は scripts/build_mcpb.py を参照）をビルドし、公式の mcpb CLI で検証して、GitHub リリースに添付します

拡張機能をローカルでビルドするには、uv が必要です。 python scripts/build_mcpb.py を実行すると、dist/arv-mcp.mcpb が作成されます。

PyPI のバージョンは恒久的なものです。リリースに問題があった場合は PyPI でそのバージョンを取り下げ、次のパッチバージョンで置き換えます。バージョン番号を再利用することはありません。

ライセンス

MIT