homes-mcp

homes-mcp

Claude 向けの MCP サーバーとして、homes.com の不動産情報にアクセスできます。自然言語で、物件の検索、住所の特定、物件詳細の取得、価格・税金の履歴、市場レポート、保存済みの物件、写真ギャラリーの確認に加え、購入可能額や住宅ローンの計算も行えます。

⚠️ homes.com は一般消費者向けの公開 API を提供していません。このサーバーは、homes.com 自身がブラウザーに配信するサーバーレンダリング済みの HTML と Schema.org JSON-LD を、ContextMint Bridge ブラウザー拡張機能を介して、サインイン済みのご自身のブラウザータブ経由で読み取ります。すべてのリクエストは、既存のセッションを通じて実行されます。つまり、ご自身の Cookie、TLS、JS コンテキストを使用し、ブラウザーで自分でクリックした場合とまったく同じように動作します。homes.com の非公式な利用として扱ってください。ご自身の判断でご利用ください。

ツール

ツール	目的
homes_search_properties	フリーテキストの場所（市区町村／郵便番号／近隣地域）から物件情報を検索します。入力をhomes.comのURLルーティング用にスラッグ化します（空欄またはスラッグ化できない場所は、空の検索結果ではなくエラーになります）。JSON-LDのCollectionPage.mainEntity.itemListElement[]を解析します。property_type、listing_type、sort、およびprice_min／price_maxの価格帯で絞り込みます。住所、価格、ベッドルーム数／バスルーム数、平方フィート数、メイン写真、掲載エージェントと仲介会社を返します。SSRの上限（約40件）を超える場合は、truncated／total_estimatedを設定します。
homes_get_by_address	米国内の住所を1件、正規のhomes.com物件URLと不透明なハッシュに解決します。構造化された入力候補検索→スラッグ→市区町村／郵便番号による検索フォールバックの順に処理し、道路名の全トークンと部屋番号を検証します。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に含まれる画像は1枚のみです）。各写真について{ url, position, alt? }を返し、homes.comのCDN上の画像に絞り込みます。
homes_bulk_get	1回の呼び出しで最大200件の物件の構造化レコードを取得します（行ごとのエラーを返し、入力順を保持します）。
homes_compare_properties	2～8件の物件を、項目をそろえたサマリーテーブルで並べて比較します。対象ごとのエラーは行ごとに記録されます。並列取得します。
homes_get_nearby_listings	詳細ページにある「この物件の近くで販売中の住宅」のクロスリンクカードを取得します（販売中。オプションで賃貸物件も取得可能）。返すのはURLと住所のみです。
homes_get_history	価格履歴と税金履歴を1回の取得でまとめて返します。listing_events、ownership_events、lien_events、正規化されたevents_normalized、およびtax_recordsを含みます。events_normalizedでは、price_change_pctはPriceChange行にのみ設定されます。それ以外の行では、homes.comの「List to Sale」の数値を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から算出します。場所が空欄またはスラッグ化できない場合は、空の市場データではなくエラーになります。
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. 安定性は保証されません。 このサーバーは、URL の形式（/<city>-<state>/、/property/<slug>/<id>/）が予告なく変更される可能性のある SSR ページから、Schema.org の JSON-LD（<script type="application/ld+json">）と DOM 内の <img> タグを読み取ります。動作しなくなることがあります。停止することもあります。こちらに代わって保守する責任のないインターフェースであるため、これは想定どおりです。

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 のリリースから入手してください。

• Chrome： Chrome 用の zip をダウンロードして解凍し、chrome://extensions → デベロッパー モードをオンにする → パッケージ化されていない拡張機能を読み込む → 解凍したフォルダーを選択します。
• Safari： 現時点では利用できません。拡張機能は ContextMint アプリに同梱される予定ですが、公開ダウンロードリンクはありません。今は Chrome をご利用ください。

入手先について。 ContextMint Bridge は、同じメンテナーによる fetchproxy のブラウザー拡張機能で、新しい名前で公開されています。fetchproxy の README にある拡張機能の項目からもリンクされています。ソースコードは公開されている nullnet-app/contextmint-bridge にあります。自分でビルドするか、公開リリースの zip と、その横にある .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、JavaScript の実行コンテキストは、すでに画面に表示されているページとすべて一致します。ヘッドレスブラウザーによる代替、別個の ID、サードパーティーのプロキシは使わず、実際のブラウザーが自身の権限で動作し、MCP サーバーがリクエスト内容を選択します。

homes.com のページは SSR React で構成されており、公開 JSON API はありません。各ツールは、各ページに埋め込まれた Schema.org の JSON-LD ブロック（<script type="application/ld+json">）からデータを抽出します。検索ページでは、リスティングが CollectionPage.mainEntity.itemListElement[] に格納されています。詳細ページでは、mainEntity（住所、広さ、地理情報）と offers.offeredBy[]（掲載エージェント）を含む RealEstateListing グラフノードが出力されます。JSON-LD に含まれるメイン画像は 1 枚だけなので、写真は 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