deal-locator-mcp

# Tool List **MCP Server that converts public data from the Ministry of Land, Infrastructure and Transport into practical tools for real estate agents.** * Converts masked commercial real transaction data into usable information * Provides tools for searching, tracking, and analyzing real estate transactions > The Ministry of Land, Infrastructure and Transport masks the lot numbers of commercial real transactions, making it difficult to identify specific buildings. deal-locator uses the building register to reverse-match and identify the building.      ## Table of Contents * [**For First-Timers**](#for-first-timers) → [1-Minute Summary](#1-minute-summary) · [Scope](#scope) · [Installation](#installation) · [6 Tools](#6-tools) * [**If You Get Stuck**](#if-you-get-stuck) → [Matching Reliability](#matching-reliability) · [FAQ](#faq) · [Limitations and Precautions](#limitations-and-precautions) <details> <summary>Expand Table of Contents</summary> * [1-Minute Summary](#1-minute-summary) * [Scope](#scope) * [What's Included](#whats-included) * [Installation](#installation) * [6 Tools](#6-tools) * [1. `resolve_address` — Address and Lot Confirmation](#1-resolve_address-address-and-lot-confirmation) * [2. `deal_card_search` — Comprehensive Deal Search](#2-deal_card_search-comprehensive-deal-search) * [3. `deal_history` — Transaction History](#3-deal_history-transaction-history) * [4. `area_scan` — Area Scan](#4-area_scan-area-scan) * [5. `match_explain` — Matching Explanation](#5-match_explain-matching-explanation) * [Matching Reliability](#matching-reliability) * [6. `deal_card_create` — Data Card](#6-deal_card_create-data-card) * [FAQ](#faq) * [Storage Structure](#storage-structure) * [Limitations and Precautions](#limitations-and-precautions) * [Notice](#notice) * [License](#license) </details> ## 1-Minute Summary The Ministry of Land, Infrastructure and Transport provides masked commercial real transaction data. deal-locator uses the building register to reverse-match and identify specific buildings. ``` Example: 영등포동 8* · 4.4 billion KRW · Land: 61㎡ / Total Floor Area: 107.7㎡ / 1985 ↓ The only matching values are: 영등포동 86 ( 76, 북촌로5길 ) — Accurate Matching: 0.97 ``` All values are from official API measurements. If no results are found, `[NOT_FOUND]` is returned. ## Scope * Currently handles **commercial buildings (general type) sales** * Will expand to include **land, factories, roads, etc.** | Category | Item Type | |---|---| | ✅ Currently Handled | **Commercial Buildings (General Type) Sales** | | ⏳ Planned Expansion | Land · Factories · Roads, etc. | ## What's Included | Component | Content | |---|---| | 5 Query Tools | Lot number · History · Area scan · Matching explanation — all read-only | | 1 Card Tool | Generate data card PNG (for customers or social media) | | Matching Engine | Reverse-match building register + re-anchor lot numbers, calculate reliability | | Cache | 15 minutes · 128 cases — re-querying API is not required | ## Installation > **At a Glance** — ① Obtain authentication key → ② Install uv → ③ Register plugin (recommended) or Desktop. This is required. > ④ Card functionality · ⑤ Pre-warming are optional. ### 1. Obtain Authentication Key (Required) Apply for and obtain **decoding authentication key** from: * Ministry of Land, Infrastructure and Transport _Commercial Real Estate Transaction Data * Building HUB _Building Register Information Service Approval usually takes a few minutes to an hour. ### 2. Install uv (Required) ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### 3-A. Install Plugin (Recommended — includes `/commands`) Install plugin and 6 MCP tools with **slash commands**. First, place authentication key in home folder as a single file. In terminal: ```bash echo 'DEAL_LOCATOR_SERVICE_KEY=obtained_decoding_authentication_key' > ~/.deal-locator.env chmod 600 ~/.deal-locator.env ``` Then, in Claude: ```bash /plugin marketplace add syleedlabs/deal-locator-mcp /plugin install deal-locator@dlabs ``` Restart to use commands. | Command | Function | | --- | --- | | `/area-scan` | Area scan for commercial building prices and trends | | `/deal-card` | Search for latest transaction data for a lot number | | `/deal-history` | Transaction history for a lot number | | `/match-explain` | Matching explanation for a lot number | | `/resolve-address` | Address and lot confirmation | | `/deal-card-image` | Generate data card PNG | ### 3-B. Register with Claude Desktop (Tools only) Settings → Developer → Edit Settings → `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": "obtained_decoding_authentication_key" } } } } ``` Restart Claude Desktop to use tools. ## 6 Tools | Tool | Function | Example Usage | |---|---|---| | `resolve_address` | Address and lot confirmation | "Confirm address for 소격동 86" | | `deal_card_search` | Comprehensive deal search for a lot number | "Find transaction data for 소격동 86" | | `deal_history` | Transaction history for a lot number | "Show transaction history for this building" | | `area_scan` | Area scan for commercial building prices | "Scan prices for 성수동1가" | | `match_explain` | Matching explanation for a lot number | "Explain matching for 영등포동8가 34-20" | | `deal_card_create` | Generate data card PNG | "Create card for this building" | ## 1. `resolve_address` — Address and Lot Confirmation **Usage** ``` /resolve-address 종로구 소격동 86 ``` **Result** ``` 종로구 소격동 86 · 법정코드 11110-14200 Lot configuration: single (no sub-lot numbers) ``` **Explanation** * Confirm address and lot configuration before proceeding with other queries. ## 2. `deal_card_search` — Comprehensive Deal Search **Usage** ``` /deal-card 종로구 소격동 86 ``` **Result** ``` 216.3842 billion KRW · 2026-05-14 · Accurate Matching: 0.97 Land: 361㎡ (109.2py) · Total Floor Area: 356.18㎡ (107.7py) · 1981 Land price per py: 1.9815 billion KRW/py · Type: Residential · Seller: Corporation → Buyer: Corporation 북촌로5길 76 (소격동) ``` **Explanation** * Comprehensive deal search for a lot number, including reliability score. ## 3. `deal_history` — Transaction History **Usage** ``` /deal-history 성수동1가 685-442 ``` **Result** ``` [성동구 성수동1가 685-442] Matching Transaction History · Last 24 months ■ 2026-06-18 575 million KRW Accurate Matching: 0.97 Corporation → Corporation ■ 2025-11-27 553 million KRW Accurate Matching: 0.97 Corporation → Corporation → Re-transaction in 7 months, +220 million KRW (+4.0%) Land: 136㎡(41.1py) · Total Floor Area: 209.34㎡(63.3py) · 1990 · Type: Residential ※ Excluding 6 cancellation reports ``` **Explanation** * Transaction history for a lot number, including reliability scores. ## 4. `area_scan` — Area Scan **Usage** ``` /area-scan 성수동1가 # District: price statistics + individual transactions /area-scan 성동구 # District: district-wide statistics + price rankings by district ``` **Result** — Example for recent quarter (3 months) ``` [성동구 성수동1가] Recent 3 months (2026 Q2) · Commercial Buildings: 12 cases Land price per py: Average 160.28 million KRW · Median 161.36 million KRW (p25 145.0 million ~ p75 209.0 million) Total Floor Area price per py: Average 77.7 million KRW · Median 85.3 million KRW Sample: 14 cases in district → 2 cases of collective housing excluded · 2 cancellation reports excluded → 12 cases ``` **Explanation** * Area scan for commercial building prices and trends. ## 5. `match_explain` — Matching Explanation **Usage** ``` /match-explain 영등포동8가 34-20 ``` **Result** ``` [영등포동8가 34-20] Matching Explanation · Accurate Matching: 0.90 (stage2) Transaction: 440 million KRW · 2026-05-06 (masked lot number '영등포동8가 3*') Building Register (Anchor) vs Transaction Total Floor Area 31.21㎡ = 31.21㎡ ✓ Match Year of Construction 1985 = 1985 ✓ Match Land Area 21.78㎡ vs 22.8㎡ Δ 1.02㎡ (reporting rounding error level) → 2 out of 3 attributes match exactly + minor land area difference → 'stage2 downgrade' but labeled as 'Accurate Matching' ``` **Explanation** * Matching explanation for a lot number, including reliability score. ### Matching Reliability | Label | Meaning | |---|---| | Accurate / Accurate Matching | Building register values match exactly — virtually the same lot | | Estimated Matching | Similar specifications — **may be adjacent building with same specs** | | Candidate | Candidate level — do not cite without confirmation | ## 6. `deal_card_create` — Data Card Creates a 4:5 card (2160×2700) with measured values on top of a building photo. **Usage** ``` /deal-card-image 영등포구 영등포동8가 34-20 [building photo] ``` > Direct call: `deal_card_create(address="영등포구 영등포동8가 34-20", photo="~/사진.jpg")` **Result** — Creates a data card with measured values. <table> <tr> <td align="center"><b>Building Photo (Input)</b></td> <td align="center"><b>Data Card (Output)</b></td> </tr> <tr> <td><img src="assets/deal-card-create-input.png" width="280" alt="영등포동8가 34-20 Building Photo (Input)"></td> <td><img src="assets/deal-card-create-example.png" width="280" alt="영등포동8가 34-20 Data Card (Output)"></td> </tr> </table> > 영등포구 영등포동8가 34-20 · Transaction Date: 2026-05-06 · Sale Price: 440 million KRW · Land: 7py (land price per py: 637.7 million KRW) · Total Floor Area: 9py · Year of Construction: 1985 · Accurate Matching: 0.90. **Explanation** * **Matching reliability is displayed on the card.** The card includes a reliability score to ensure accuracy. ## FAQ **Q. Does it support apartments?** > No. **Seoul · Commercial · Sales** only (v1). Apartments, officetels, single-family homes, land, and monthly rentals are out of scope. **Q. Why is the first query so slow?** > It takes tens of seconds to several minutes to load the entire building registry. Subsequent queries within 15 minutes are cached and return immediately. **Q. Are canceled transactions included?** > No. **Canceled transactions are excluded from aggregation** and their count is provided. **Q. There are transactions with unclear addresses.** > This is when a matching parcel cannot be found. It is marked as `masking not restored` in the `area_scan` results, and **the amount and area are actual measurements**, but the address is not confirmed. **Q. I don't want to put the authentication key in the configuration file.** > Place a `.env` file in the execution folder (or one level up) and it will be read automatically (see `.env.example`). **Never commit `.env`**. > > For security reasons, **only `DEAL_LOCATOR_*` and `DATA_GO_KR_API_KEY` are read**. Other lines in `.env` are ignored to prevent settings (e.g., proxies) from being mixed in when running the server in someone else's project folder. **Q. When creating a card, does it read arbitrary files?** > `photo` **determines if it's an image based on its content** (PNG, JPEG, GIF, WebP). If it's not an image, rendering stops. Card rendering runs with JavaScript disabled and all network requests blocked, so scripts in card values do not execute or make external requests. ## Repository Structure ``` deal-locator-mcp/ ├─ src/deal_locator/ │ ├─ server.py MCP Server — defines 6 tools and structured output │ ├─ core/ Matching engine (title matching, subsidiary addresses, pipeline) │ └─ render/ Data card rendering (template + Pretendard font) ├─ tests/ 114 tests ├─ server.json MCP registry metadata └─ .env.example ``` ## Limitations and Precautions This tool **explicitly states what it cannot do**. Read this before citing any numbers. **Scope** - **Only Seoul, commercial, and sales (v1)**. Apartments, officetels, single-family homes, land, and monthly rentals outside Seoul are not queried. - **Only general buildings (not aggregate buildings)** — all responses exclude aggregate (divided commercial) transactions. The market prices and unit prices provided are based on general buildings; **do not cite a single unit's price as representative**. The number of excluded aggregate transactions is provided in the response as `jiphap_excluded`. **Matching Limitations** - **Matching is probabilistic, not a registry**. `Estimated matches` may be adjacent buildings with similar specs, and `adjacent candidates` should not be cited without verification. Use `match_explain` to verify the basis for matches below `estimated matches`. - **Some transactions have unclear addresses**. If a matching parcel is not found, it is marked as `masking not restored` — **the amount and area are actual measurements, but the address is not confirmed**. **Data and Statistics** - **Canceled transactions are excluded from aggregation**, and their count is provided to prevent misinterpreting canceled values as actual transactions. - **`area_scan` statistics may have a thin sample size**. General building sales can range from 1 to 7 transactions per month, depending on the dong. Always check `coverage` (decomposition: total, aggregate excluded, canceled excluded, masking not restored) to assess representativeness. - **First queries are slow, and caches may not be up-to-date**. Initial queries for a gu or dong take tens of seconds to several minutes (then cached for 15 minutes). Actual transactions are updated monthly, so old caches or pre-warmed data may not reflect the latest transactions. **Principles** - **Returns `[NOT_FOUND]` if no results are found** — it indicates a lack of data, not a value of zero. Do not fabricate values (a designed signal to prevent AI hallucinations). - **No personal information (e.g., owner) is handled**. Only publicly available actual transaction and building registry measurements are returned. > For judgments beyond the results (e.g., contracts, appraisals, customer presentations), **always verify the original text**. > Please also read the notice below. ## Notice The results of this tool are **reference materials and not substitute for official confirmation or explanation documents**. The original public registers (Ministry of Land, Infrastructure and Transport's actual transaction disclosure system, building registry) always take precedence. Verify the original text before presenting it to customers or using it for contract decisions. The creator is not responsible for the accuracy of matching results. Source: Ministry of Land, Infrastructure and Transport's Actual Transaction Disclosure System · BuildingHUB (Public Data Portal [data.go.kr](http://data.go.kr)) ## License MIT License — Copyright (c) 2026 DLABS The included font [Pretendard](https://github.com/orioncactus/pretendard) is under the SIL Open Font License 1.1. The MIT License does not apply to the font — see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). ## Contact DLABS · [github.com/syleedlabs](https://github.com/syleedlabs)