deal-locator-mcp

# 交易定位 — 商业用不動産取引一覧 MCP **国土交通部 公開データ（実績価格・建築物台帳）を不動産仲介業者業務に活用するMCPサーバー.** 不動産取引の物件詳細検索、隠れた実績価格の特定、取引履歴の追跡、 住所から区/丁/番地・法定コード・筆地確認、顧客用データカードの自動作成まで — **会話ワンラインで.** > 国土交通部は商業用不動産の実績価格の地番を `ソギョンドン 8*` のように **マスキング**して公開します。 > 皆が「どの建物か分からない」と言うところで、deal-locatorは建築物台帳の表題部で **逆マッチングしてその建物をたどり**、その上に時価・履歴・コンテンツを載せたオールインワンツールです。      --- ## 目次 **初めての方へ** → [1分 요약](#1分-概要---これは何ですか) ・ [扱う範囲](#扱う範囲-v1) ・ [インストール](#インストール) ・ [ツール6種](#ツール6種) **使いながら詰まったら** → [マッチング信頼度](#マッチング信頼度は必ず一緒に読んでください) ・ [FAQ](#faq) ・ [限界・注意事項](#限界・注意事項) <details> <summary>全体の目次を表示</summary> - [1分概要 — これは何ですか？](#1分-概要---これは何ですか) - [扱う範囲 (v1)](#扱う範囲-v1) - [何が入っていますか？](#何が入っていますか) - [インストール](#インストール) - [ツール6種](#ツール6種) - [1. `resolve_address` — 住所・筆地確認](#1-resolve_address-住所・筆地確認) - [2. `deal_card_search` — 物件総合確認](#2.deal_card_search-物件総合確認) - [3. `deal_history` — 実績価格取引履歴確認](#3.deal_history-実績価格取引履歴確認) - [4. `area_scan` — 区/丁目 実績価格最新相場確認](#4.area_scan-区丁目-実績価格最新相場確認) - [5. `match_explain` — マッチング根拠](#5.match_explain-マッチング根拠) - [マッチング信頼度は必ず一緒に読んでください](#マッチング信頼度は必ず一緒に読んでください) - [6. `deal_card_create` — データカード](#6.deal_card_create-データカード) - [FAQ](#faq) - [リポジトリ構造](#リポジトリ構造) - [限界・注意事項](#限界・注意事項) - [告知](#告知) - [ライセンス](#ライセンス) </details> --- ## 1分概要 — これは何ですか？ 国土交通部の商業用不動産実績価格は、一般建物の地番を `ソギョンドン 8*` のように **マスキング**して公開します。 そこで「この建物がいくらで売れたか」を確認するには、台帳を一つ一つ照合しなければなりませんでした。 このサーバーは **建築物台帳の表題部(建築年度・延床面積・敷地面積)** と **付属地番台帳**で逆マッチングしてその筆地を特定します。 ``` ソギョンドン 8* ・ 216億 3,842万円 ・ 敷地 361㎡ / 延床面積 356.18㎡ / 1981年 ↓ 表題部3つの値が正確に一致する筆地は1つだけ ソギョンドン 86 (北村路5길 76) — 正確マッチング 0.97 ``` すべての数値は、公共データポータル(data.go.kr)公式API実測値です。結果がなければ `[NOT_FOUND]` を返します — **AIが数値を捏造できないように**設計しました。 --- ## 扱う範囲 (v1) > **必ず確認してください。** 現在は **建物(タイプ「一般」) 商業用建物**の売買を扱います。 ここで出てくる相場・平当金はすべてこの建物基準であり、 今後 **土地・工場・道路**など他の物件種類に扱う範囲を広げる予定です。 | 区別 | 物件種類 | |---|---| | ✅ 今扱う | **建物(タイプ「一般」) 商業用建物** 売買 | | ⏳ 拡張予定 | 土地・工場・道路など | > ※ 集合(区分マンション)取引は現在除外されます。 --- ## 何が入っていますか？ | 構成 | 内容 | |---|---| | 照会ツール5種 | 地番・履歴・地域スキャン・マッチング根拠 — 全て読み専用 | | カードツール1種 | 照会結果をデータカードPNG 1枚で(顧客提示・SNS用) | | マッチングエンジン | 表題部逆マッチング+付属地番再アンカー、段階別信頼度算出 | | キャッシュ | 15分・128件 — 同じ地番再照会はAPIをもう一度叩きません | --- ## インストール > **一目瞭然** — ① 認証キー発行 → ② uv インストール → ③ プラグイン(推奨)またはDesktop登録。ここまでが必須です。 > ④ カード機能・⑤ プリウォーミングは選択肢なので、急いでいる場合は③までで大丈夫です。 ### 1. 認証キー発行 (必須) [公共データポータル](https://www.data.go.kr) で以下2つを活用申請して **デコード認証キー**を受け取ります。 - 国土交通部_商業用不動産取引報告資料 - 建築HUB_建築物台帳情報サービス 承認まで通常数分~1時間かかります。 ### 2. uv インストール (必須) ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### 3-A. プラグインでインストール (推奨 — `/コマンド`まで一緒に付きます) プラグインでインストールするとMCPツール6個と **スラッシュコマンド6個**が一度に付きます。 まず認証キーをホームフォルダにファイルとして置きます。ターミナルで: ```bash echo 'DEAL_LOCATOR_SERVICE_KEY=発行された_デコード_認証キー' > ~/.deal-locator.env chmod 600 ~/.deal-locator.env ``` その後、Claude で: ``` /plugin marketplace add syleedlabs/deal-locator-mcp /plugin install deal-locator@dlabs ``` 再起動すると以下のコマンドをすぐに使えます。 | コマンド | 処理 | | --- | --- | | `/area-scan` | 区・丁目 建物相場と分岐推移 | | `/deal-card` | 地番 実績価格 1件照会 | | `/deal-history` | その地番の手替わり履歴 | | `/match-explain` | なぜこの建物と判断したのか根拠 | | `/resolve-address` | 住所・筆地構成確認 | | `/deal-card-image` | データカードPNG作成 | > 認証キーファイルは `~/.deal-locator.env` → `~/.config/deal-locator/.env` の順で探します。 > プロジェクトフォルダに `.env` がある場合はそちらが優先されます。 ### 3-B. Claude Desktop に直接登録 (ツールのみ) 設定 → 開発者 → 設定編集 → `claude_desktop_config.json` ```json { "mcpServers": { "deal-locator": { "command": "uvx", "args": ["--from", "git+https://github.com/syleedlabs/deal-locator-mcp", "deal-locator-mcp"], "env": { "DEAL_LOCATOR_SERVICE_KEY": "発行された_デコード_認証キー" } } } } ``` Claude Desktop を再起動するとツール6個が表示されます。 > ⚠️ **この設定ファイルには認証キーが平文で入ります。** 共有・スクリーンショット・ > リモートサポート時に露出しないように注意してください。キーが漏出した場合、公共データポータルで > 即時再発行できます。ファイルにキーを置きたくない場合は、以下のFAQの`.env`方式を使用してください。 ### 4. カード機能を使うには (選択) カードはブラウザエンジンで画像を描きます。初回のみ: ```bash uvx --from git+https://github.com/syleedlabs/deal-locator-mcp playwright install chromium ``` スキップしても照会ツール5個は正常に動作します。 ### 5. 初回照会を早く (選択 — プリウォーミング) 区・丁目を **最初に**照会すると、国土交通省APIから12ヶ月分受け取るため20～35秒かかります (1回受けた区はその後すぐに返します)。あらかじめ埋め込んでおくと: ```bash # 東京 25区・12ヶ月分キャッシュ埋め込み (API 300回、数分かかります — 1回のみ) uvx --from git+https://github.com/syleedlabs/deal-locator-mcp deal-locator-warm # よく見る区だけ: deal-locator-warm --gus 荒川区 港区 品川区 ``` 認証キーは、照会と同じ `~/.deal-locator.env` を使用します。途中で切れても、再実行すると 残りのものから続けて受けます。実績は毎月更新されるため、必要なら月1回くらい再実行してください。 --- ## ツール6種 | ツール | 処理 | このように呼びます | |---|---|---| | `resolve_address` | 住所・筆地確認 | "ソギョンドン 86 住所確認してください" | | `deal_card_search` | 物件詳細確認 | "ソギョンドン 86 実績価格教えて" | | `deal_history` | その地番の手替わり履歴 | "この建物の取引履歴全部見せて" | | `area_scan` | 丁目別相場スキャン (地番不要) | "成城 1-1 平当 4.5-5.5億 取引" | | `match_explain` | マッチング根拠公開 — 表題部値 vs 取引行値対照 | "このマッチングなぜこんなにされたの？" | | `deal_card_create` | データカード作成 | "この物件でカード作って" | 前の5個は **読み専用** です。ファイルを生成したり外部に何かを送信したりしません。 各ツールの **使い方 → 結果物 → 説明** 順に整理した実行例です。 値は全て公式API実測値であり、表示は読みやすくするために整理されています。 --- ## 1. `resolve_address` — 住所・筆地確認 **使い方** ``` /resolve-address ソギョンドン 86 ``` **結果物** ``` ソギョンドン 86 · 法定コード 11110-14200 筆地構成: 単一 (付属地番なし) ``` **説明** - 他の照会が止まっている場合に、住所が正しく捕まっているか・合筆/付属地番があるかを確認します。 - `照会失敗` は「単一筆地」ではなく **未確認** なので区別して読んでください。 --- ## 2. `deal_card_search` — 物件総合確認 **使い方** ``` /deal-card ソギョンドン 86 ``` **結果物** ``` 216億 3,842万円 · 2026-05-14 · 正確マッチング 0.97 敷地 361㎡ (109.2坪) · 延床面積 356.18㎡ (107.7坪) · 1981年竣工 敷地平当金 1億 9,815万円/坪 · 第1種一般住居 · 売主 法人 → 買主 法人 北村路5길 76 (ソギョンドン) ``` **説明** - 地番1つの最新実績を総合カード1枚で。信頼度(正確マッチング 0.97)と一緒に読みます。 --- ## 3. `deal_history` — 実績価格手替わり履歴確認 **使い方** ``` /deal-history 成城1-1-1 ``` **結果物** ``` [城東区 成城1-1-1] マッチング実績履歴 · 最近24ヶ月 ■ 2026-06-18 5億 7,000万円 正確マッチング 0.97 法人 → 法人 ■ 2025-11-27 5億 5,300万円 正確マッチング 0.97 法人 → 法人 → 約7ヶ月ぶりに再取引、+2,000万円 (+4.0%) 敷地 136㎡(41.1坪) · 延床面積 209.34㎡(63.3坪) · 1990年 · 第2種一般住居 ※ 解除申請 6件 除外 ``` **説明** - 地番の手替わりを最新順に — 再取引・価格推移を一目瞭然。物件ごとの信頼度が異なる場合があります。 --- ## 4. `area_scan` — 区/丁目 実績価格最新相場確認 **使い方** ``` /area-scan 成城1-1 # 丁目: 相場統計 + 個々の取引 /area-scan 城東区 # 区: 区全体の統計 + 丁目別平当金ランキング ``` **結果物** — 丁目を照会した場合、最近1ヶ月(3ヶ月)の例です。 ``` [城東区 成城1-1] 最近3ヶ月(2026 Q2) · 建物 12件 敷地平当金 平均 1億 6,028万円 · 中央値 1億 6,136万円 (p25 1.45億 ~ p75 2.09億) 延床面積平当金 平均 7,770万円 · 中央値 8,530万円 標本 丁目全体 14件 → 集合(区分マンション) 2件 除外 · 解除 2件 除外 → 建物 12件 集計 ``` **説明** - 丁目を渡すと相場統計と個々の取引を、区を渡すと区全体の統計と丁目別平当金ランキングを返します。 - 丁目の平均相場は国土交通省の原文に近い `stats` で答えます。 - `coverage`(サンプルの分解能)を一緒に見なければ、標本が代表性を持っているかどうかを判断できません。 --- ## 5. `match_explain` — マッチング根拠 **使い方** ``` /match-explain ソギョンドン8-34-20 ``` **結果物** ``` [ソギョンドン8-34-20] マッチング根拠 · 正確マッチング 0.90 (stage2) 取引 4億 4,000万円 · 2026-05-06 (地番マスキング 'ソギョンドン8-3*') 表題部(アンカー) vs 取引行 延床面積 31.21㎡ = 31.21㎡ ✓ 一致 建築年度 1985 = 1985 ✓ 一致 敷地面積 21.78㎡ vs 22.8㎡ Δ 1.02㎡ (申告 四捨五入誤差レベル) → 3属性のうち2個正確に一致 + 敷地面積は僅差 → 'stage2 降格'だがラベルは「正確マッチング」 ``` **説明** - 国土交通省の実績価格は地番を `ソギョンドン8-34-20 3*` のように **マスキング**して公開します。このツールは建築物台帳の表題部(建築年度・延床面積・敷地面積)で **逆マッチング**して「この建物」と特定しますが、 **マッチング信頼度**はその特定がどれくらい確実であるかを意味します。 - `推定マッチング`であれば **同じスペックの隣の建物**かもしれませんし、その値を顧客・報告書で「この建物の実績価格」として引用すると **間違った建物の価格を述べるエラー**になります。 - `match_explain`は、どのような表題部の値でどのように特定したのか(アンカー vs 取引行)を対照し、引用前にそのリスクを直接判断させます。 ### マッチング信頼度は必ず一緒に読んでください | 表示 | 意味 | |---|---| | 確定 / 正確マッチング | 表題部の値が正確に一致 — ほぼその筆地 | | 推定マッチング | 類似スペックで絞り込んだもの — **同一スペックの隣の建物かもしれません** | | 近隣候補 | 候補レベル — 確認せずに引用しないでください | `推定マッチング`以下の場合は、顧客に提示する前に `match_explain` で根拠を確認してください。 --- ## 6. `deal_card_create` — データカード 建物の写真の上に実測値を載せた 4:5 カード(2160×2700)を作成します。プロモーション文言は入りません — カードの全ての文字は実測値か固定ラベルです。 **使い方** ``` /deal-card-image 荒川区 ソギョンドン8-34-20 [建物の写真] ``` > 直接呼び出し: `deal_card_create(address="荒川区 ソギョンドン8-34-20", photo="~/写真.jpg")` **結果物** — 建物の写真(入力)に実測値を載せてカード(出力)を作成します。 <table> <tr> <td align="center"><b>建物の写真 (入力)</b></td> <td align="center"><b>データカード (結果物)</b></td> </tr> <tr> <td><img src="assets/deal-card-create-input.png" width="280" alt="ソギョンドン8-34-20 建物の写真(入力)"></td> <td><img src="assets/deal-card-create-example.png" width="280" alt="ソギョンドン8-34-20 データカード(結果物)"></td> </tr> </table> > 荒川区 ソギョンドン8-34-20 · 取引日 2026-05-06 · 売買 4.4億 · 土地 7坪(平当金 6,377万円/坪) · 延床面積 9坪 · 準工業 · 1985年竣工 · 正確マッチング 0.90. **説明** - **マッチング信頼度はカードに表示されます**。画像は会話から離れて一人で歩くので、 根拠が常に付随している必要があります。`推定マッチング`以下の場合は色で区別されます。 - **建物の写真がなければカードを作成せずに停止します**。写真なしで作成するとグレーの板が出るので、結局作り直すことになります。写真のパスを指定するか、 そのまま進める場合は `allow_no_photo=true` を指定してください。 - 保存場所は `~/deal-locator-cards/<日付>/` です (`DEAL_LOCATOR_CARD_DIR` で変更可能)。 --- ## FAQ **Q. マンションもできますか？** > いいえ。 **東京・商業用不動産・売買**のみ扱います(v1)。マンション・アパート・戸建て・土地・賃貸は範囲外です。 **Q. 初回照会が遅すぎます。** > 建築物台帳全体を呼び出すため、数十秒~数分かかります。その後15分間はキャッシュされるので、同じ区の照会はすぐに返ります。 **Q. 契約キャンセルされた取引も含まれますか？** > いいえ。 **解除申請された物件は集計から除外**し、その件数を通知します。 **Q. 地番が特定できない取引があります。** > 表題部と一致する筆地が見つからない場合です。 `area_scan` 結果に `マスキング 未復元` と表示され、その物件の **金額・面積は実測値**ですが、住所は確定したものではありません。 **Q. 認証キーを設定ファイルに入れたくありません。** > 実行フォルダ(またはその上の1レベル)に `.env` を置くと自動で読み込みます(`.env.example` を参照)。 `.env` は絶対にコミットしないでください。 > > セキュリティ上、 **`DEAL_LOCATOR_*` と `DATA_GO_KR_API_KEY` だけ読み込みます。** `.env` の他の行は無視されます — 他のプロジェクトフォルダでサーバーを立てた時に、その設定(プロキシなど)が混ざって入ってくるのを防ぐためです。 **Q. カード作成時に任意のファイルが読み込まれませんか？** > `photo` は **ファイル内容で画像かどうか判別**します(PNG・JPEG・GIF・WebP)。画像でない場合はレンダリングせずに停止します。カードレンダリングはJavaScriptをオフにした状態で回り、すべてのネットワークリクエストはブロックされるため、カード値にスクリプトが混ざっても実行されず、外部に流出することもありません。 --- ## リポジトリ構造 ``` deal-locator-mcp/ ├─ src/deal_locator/ │ ├─ server.py MCPサーバー — ツール6個定義・構造化出力 │ ├─ core/ マッチングエンジン (表題部逆マッチング・付属地番・パイプライン) │ └─ render/ データカードレンダリング (テンプレート + Pretendard フォント) ├─ tests/ 114個 ├─ server.json MCPレジストリメタデータ └─ .env.example ``` --- ## 限界・注意事項 このツールが **できないこと**を最初に明らかにします。数値を引用する前に必ず一緒に読んでください。 **扱う範囲** - **東京・商業用不動産・売買のみです (v1)。** マンション・アパート・戸建て・土地・賃貸、 そして東京以外は照会されません。 - **建物(一般) のみ扱います — 集合(区分マンション)取引は全ての応答で除外されます。** ここで出てくる 相場・平当金は全て建物基準であり、 **区分マンション 1区画の相場として引用してはいけません。** 除外された 集合取引件数は応答の `jiphap_excluded` で一緒に通知されます。 **マッチングの限界** - **マッチングは確率であり、登記簿ではありません。** `推定マッチング` は同一スペックの隣の建物かもしれませんし、 `近隣候補` は確認せずに引用すると危険です。 `推定マッチング`以下の場合は `match_explain` で根拠を確認してから使ってください。 - **特定できない取引があります。** 表題部と一致する筆地が見つからない場合は `マスキング 未復元` と 表示されます — その物件の **金額・面積は実測値ですが、住所は確定したものではありません。** **データ・統計** - **解除申請(契約キャンセル)物件は集計から除外**し、その件数を通知します。キャンセルされた値を実績として 誤認しないようにするための措置です。 - **`area_scan`統計はサンプルが薄い場合があります。** 建物取引は丁目により月1~7件なので、 必ず `coverage`(サンプル分解能: 全体・集合除外・解除除外・マスキング未復元)を一緒に見て、 代表性を判断してください。 - **初回照会は遅く、キャッシュは最新ではないかもしれません。** 区・丁目初回照会は建築物台帳全体を受け取るため、 数十秒~数分かかります(その後15分キャッシュ)。実績は毎月更新されるため、古いキャッシュ・プリウォーミングデータは 最新の取引を反映していない可能性があります。 **原則** - **結果がなければ `[NOT_FOUND]` を返します — データがないわけではなく、0円ではありません。** この場合、 数値を捏造してはいけません(AIが幻覚を起こさないように設計されたシグナルです)。 - **所有者などの個人情報は扱いません。** 公開された実績・建築物台帳の実測値を返します。 > 上記の限界を超える判断(契約・査定・顧客提示)には必ず原文を直接確認してください。 > 以下告知を一緒に読んでください。 --- ## 告知 このツールの結果は **参考資料であり、仲介対象不動産確認・説明書ではありません。** 公的台帳の原文(国土交通省 実績価格公開システム、建築物台帳)がいつでも優先します。 顧客に提示したり契約判断に使ったりする前に、原文を直接確認してください。 マッチング結果の正確性について、制作者は責任を負いません。 出典: 国土交通省 実績価格公開システム · 建築HUB (公共データポータル data.go.kr) --- ## ライセンス MIT License — Copyright (c) 2026 ディ랩ス(DLABS) 同梱フォント [Pretendard](https://github.com/orioncactus/pretendard) は SIL Open Font License 1.1 です。フォントにはMITは適用されません — [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 参照。 ## お問い合わせ ディ랩ス(DLABS) · [github.com/syleedlabs](https://github.com/syleedlabs)