서울 상업업무용(통건물) 부동산의 국토부 마스킹 실거래가를 건축물대장 표제부로 역매칭해 특정하고, 시세 조회·이력 추적·데이터카드·CSV 내보내기까지 하는 MCP 서버입니다.
주소 해석: resolve_address — 구/동/번지·법정코드 확인, 필지 구성(단일/다필지/부속지번) 및 대표지번 파악
매물 종합 조회: deal_card_search — 지번 하나의 최신 실거래가·평단가·거래일·매도/매수·건물 스펙·매칭 신뢰도 일괄 제공
거래 이력: deal_history — 해당 지번의 손바뀜 이력 전체(최신순), 건별 신뢰도·해제신고 제외 건수 포함
지역 시세 스캔: area_scan — 구/동 단위 평단가 통계·분기 추이·동별 순위, 가격대·도로명 필터, 표본 대표성(coverage) 제공
매칭 근거: match_explain — 표제부 앵커값 vs 거래행값 대조로 왜 그 건물로 판정했는지 근거 공개(추정매칭 검증용)
데이터카드 생성: deal_card_create — 실측값만 담긴 4:5 PNG 카드 제작(신뢰도 0.90 미만 차단, 사진 필수, 신뢰도 배지 각인)
CSV 내보내기: deals_export — 서울 전역(또는 구) 실거래를 지번 복원된 CSV로 다운로드(2006년~, 장기간은 연도별 파일, 멱등 재개)
전 도구가 공공데이터 실측값만 반환하고 결과가 없으면 [NOT_FOUND]로 응답 — 수치를 추측·환각하지 않도록 설계됨
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@deal-locator-mcp 소격동 86 실거래가 알려줘"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
국토부 공공데이터(실거래가 · 건축물대장)를 공인중개사 실무로 바꾸는 MCP 서버. 구·동 평단가 시세 조회, 가려진 실거래가가 어느 건물인지 특정, 손바뀜 이력 추적, 주소 → 구/동/번지·법정코드·필지 확인, 고객용 데이터카드 자동 제작까지 — 대화 한 줄로.
국토부는 상업용 실거래가의 지번을
소격동 8*처럼 마스킹해 공개합니다. 남들이 "어느 건물인지 모른다"에서 멈출 때, deal-locator는 건축물대장 표제부로 역매칭해 그 건물을 되짚고, 그 위에 시세 · 이력 · 콘텐츠를 얹은 올인원 도구입니다.
🆕 v1.5 (2026-08) — 당월 거래가 조회에 들어옵니다. 이전에는 조회 창을 직전 달부터 세어(
months=12= 1~12개월 전) 이번 달 체결 거래가 통째로 빠졌습니다 — 실측으로 1,200억 거래(2026-08-26 체결)를 5일 뒤 조회했더니[NOT_FOUND]"실거래 없음" 이었습니다. 이제months는 당월 포함으로 셉니다. 당월은 신고기한(계약일로부터 30일)이 안 지나 표본이 얇으므로, 그 취지의 고지가 응답에 함께 나갑니다(0건이어도 '거래가 없었다'는 뜻이 아닙니다). ⚠️ 같은months값의 구간이 한 달 최신 쪽으로 이동합니다.v1.5.2 (2026-09) — "표제부없음" 오판 수정. 실재하는 지번이
[NOT_FOUND]"번지 오타/신축/멸실 가능" 으로 나오던 문제를 고쳤습니다(실측: 서초구 방배동 910-15· 우면동 72-8 — 둘 다 실제로는 각각 240억·32억 정확매칭 거래가 있었습니다). 원인은 데이터 부재가 아니라 건축물대장 표제부 수신이 조용히 중간에 끊긴 것이었고, 그 실패가 부재와 똑같은 응답으로 나갔습니다. 세 가지를 바꿨습니다. ① 건축HUB 를 https 로 부릅니다 — 평문 HTTP 는 일부 네트워크에서 중간 장비에 끊겨 "200 + 빈 본문" 으로 돌아옵니다(실측 http 7/10·평균 11.7초 vs https 10/10·평균 0.38초). ② 단건 지번 조회가 동 전체(방배동 5,432건·55페이지)를 긁지 않고 본번 지정 조회 1회로 끝납니다 — 0.8초. ③ 조회 실패와 부재를 구분합니다. 표제부를 못 받으면[NOT_FOUND]가 아니라 외부 API 오류로 나가므로, 이 응답을 근거로 부재를 단정하지 마세요.v1.5.1 (2026-09) — fastmcp 4 호환 수정. 플러그인 설치(
uvx --from git+…)가 fastmcp 4.0 을 받으면서fastmcp.tools.tool경로가 사라져 서버가 켜지지 않던 문제를 고쳤습니다(fastmcp<4상한 포함). 이미 설치한 경우 Claude Code 재시작 후에도 안 뜨면uv cache clean deal-locator-mcp를 한 번 실행하세요.v1.4 — 카드 신뢰도 게이트:
deal_card_create가 추정매칭 이하(신뢰도 0.90 미만)는LOW_CONFIDENCE로 멈춥니다. 카드 PNG 는 대화를 떠나 고객 손에 가는데, 추정매칭은 동일 스펙 옆 건물일 수 있는 상태이기 때문입니다. 근거(match_explain) 확인 후allow_estimated=true로만 발행되며, 발행된 카드에는 신뢰도 배지가 그대로 찍힙니다.v1.3 — ① 매칭 엔진 v2: 지분거래 비율매칭·자릿수 프리필터 등으로 마스킹 지번 복원율 84%(서울 25개 구 전수, 오매칭 0) ② 새 도구
deals_export: 연월 지정 서울 전역 실거래를 지번 복원된 CSV로 다운로드(2006~, 장기간은 연도별 파일) ③ 건축HUB API 응답 형식 변경 대응.
처음이라면 → 1분 요약 · 다루는 범위 · 설치 · 도구 7종 쓰다가 막히면 → 매칭 신뢰도 · FAQ · 한계 · 주의
Related MCP server: Korea Housing MCP
국토교통부 상업업무용 실거래가는 일반건물의 지번을 소격동 8* 처럼 가려서 공개합니다.
그래서 "이 건물이 얼마에 팔렸나"를 확인하려면 대장을 일일이 대조해야 했습니다.
이 서버는 건축물대장 표제부(건축년도 · 연면적 · 대지면적) 와 부속지번 대장으로 역매칭해 그 필지를 특정합니다.
소격동 8* · 216억 3,842만원 · 대지 361㎡ / 연면적 356.18㎡ / 1981년
↓ 표제부 3개 값이 정확히 일치하는 필지는 하나뿐
소격동 86 (북촌로5길 76) — 정확매칭 0.97모든 수치는 공공데이터포털(data.go.kr) 공식 API 실측값입니다. 결과가 없으면
[NOT_FOUND] 를 반환합니다 — AI가 수치를 지어내지 못하도록 설계했습니다.
📌 꼭 확인하세요.
현재는 통건물(한 필지 위 건물 한 채) 상업용건물 매매를 다룹니다. 여기서 나오는 시세·평단가는 전부 이 통건물 기준이며, 앞으로 토지 · 공장 · 도로 등 다른 물건 종류로 취급 범위를 넓혀 나갈 예정입니다.
구분 | 물건 종류 |
✅ 지금 취급 | 통건물(유형 '일반') 상업용건물 매매 |
⏳ 확장 예정 | 토지 · 공장 · 도로 등 |
※ 집합(구분상가) 거래는 현재 제외됩니다.
구성 | 내용 |
조회 도구 5종 | 지번 · 이력 · 지역 스캔 · 매칭 근거 — 전부 읽기 전용 |
카드 도구 1종 | 조회 결과를 데이터카드 PNG 1장으로 (고객 제시 · SNS용) |
매칭 엔진 | 표제부 역매칭 + 부속지번 재앵커, 6단계 신뢰도 파이프라인(지분거래 비율매칭 포함) · 표제부 완전수신 보장 |
캐시 | 15분 · 128건 — 같은 지번 재조회는 API를 다시 때리지 않습니다 |
한눈에 — ① 인증키 발급 → ② uv 설치 → ③ 플러그인(권장) 또는 Desktop 등록. 여기까지가 필수입니다. ④ 카드 기능 · ⑤ 프리워밍은 선택이니, 급하면 ③까지만 하고 바로 조회하세요.
공공데이터포털 에서 아래 2개를 활용신청하고 디코딩 인증키를 받습니다.
국토교통부_상업업무용 부동산 매매 신고 자료
건축HUB_건축물대장정보 서비스
승인까지 보통 몇 분~1시간 걸립니다.
curl -LsSf https://astral.sh/uv/install.sh | sh/명령어까지 함께 들어옵니다)플러그인으로 깔면 MCP 도구 7개와 슬래시 명령 7개가 한 번에 붙습니다.
먼저 인증키를 홈 폴더에 파일 하나로 둡니다. 터미널에서:
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재시작하면 아래 명령을 바로 쓸 수 있습니다.
명령 | 하는 일 |
| 구·동 통건물 시세와 분기 추이 |
| 지번 실거래 한 건 조회 |
| 그 지번의 손바뀜 이력 |
| 왜 이 건물로 판단했는지 근거 |
| 주소·필지 구성 확인 |
| 데이터카드 PNG 만들기 |
| 연월 지정 서울 전역 실거래 CSV 다운로드 |
인증키 파일은
~/.deal-locator.env→~/.config/deal-locator/.env순으로 찾습니다. 프로젝트 폴더에.env가 있으면 그쪽이 우선입니다.
설정 → 개발자 → 설정 편집 → claude_desktop_config.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 을 재시작하면 도구 7개가 잡힙니다.
⚠️ 이 설정 파일에는 인증키가 평문으로 들어갑니다. 화면 공유·스크린샷· 원격지원 때 노출되지 않게 주의하세요. 키가 유출된 것 같으면 공공데이터포털에서 즉시 재발급하면 됩니다. 파일에 키를 두기 싫으면 아래 FAQ 의
.env방식을 쓰세요.
카드는 브라우저 엔진으로 이미지를 그립니다. 최초 1회만:
uvx --from git+https://github.com/syleedlabs/deal-locator-mcp playwright install chromium건너뛰어도 조회 도구 5개는 정상 동작합니다.
구·동을 처음 조회하면 국토부 API 를 12개월치 받아오느라 20~35초 걸립니다 (한 번 받은 구는 이후 즉시 응답합니다). 미리 채워두려면:
# 서울 25구 · 12개월치 캐시 채우기 (API 300회, 몇 분 소요 — 한 번만)
uvx --from git+https://github.com/syleedlabs/deal-locator-mcp deal-locator-warm
# 자주 보는 구만: deal-locator-warm --gus 강남구 성동구 마포구인증키는 조회와 같은 ~/.deal-locator.env 를 씁니다. 중간에 끊겨도 다시 실행하면
남은 것만 이어서 받습니다. 실거래는 매달 갱신되니, 원하면 월 1회쯤 다시 돌리세요.
도구 | 하는 일 | 이렇게 물어보세요 |
| 주소 → 구/동/번지 + 법정코드, 필지 구성 확인 | "소격동 86 주소 확인해줘" |
| 지번 하나의 최신 실거래 종합 | "소격동 86 실거래가 알려줘" |
| 그 지번의 매칭 실거래 이력 전체 | "이 건물 거래 이력 다 보여줘" |
| 동 단위 평당가 구간 스캔 (지번 몰라도 조회) | "성수동1가 평당 4.5~5.5억 거래" |
| 매칭 근거 공개 — 표제부값 vs 거래행값 대조 | "이 매칭 왜 이렇게 나왔어?" |
| 데이터카드 PNG 1장 생성 | "이 건으로 카드 만들어줘" |
| 연월 지정 서울 전역 실거래 CSV 다운로드 | "2026년 7월 실거래 CSV로 뽑아줘" |
앞의 5개는 읽기 전용입니다. 파일을 만드는 도구는 deal_card_create(카드 PNG)와
deals_export(CSV) 둘뿐이고, 외부에 무언가를 보내지 않습니다.
각 도구를 사용방법 → 결과물 → 설명 순으로 정리한 실행 예시입니다. 값은 전부 공식 API 실측값이며, 표시는 가독성을 위해 정리한 것입니다.
resolve_address — 주소·필지 확인사용방법
/resolve-address 종로구 소격동 86결과물
종로구 소격동 86 · 법정코드 11110-14200
필지 구성: 단일 (부속지번 없음)설명
다른 조회가 막히기 전에 주소가 제대로 잡히는지 · 합필/부속지번이 있는지 먼저 확인합니다.
조회실패 는 '단일 필지'가 아니라 미확인이니 구분해서 읽으세요.
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콜로. 신뢰도(정확매칭 0.97)를 함께 읽으세요.
deal_history — 실거래가 손바뀜 이력 확인사용방법
/deal-history 성수동1가 685-442결과물
[성동구 성수동1가 685-442] 매칭 실거래 이력 · 최근 24개월
■ 2026-06-18 57억 5,000만원 정확매칭 0.97 법인 → 법인
■ 2025-11-27 55억 3,000만원 정확매칭 0.97 법인 → 법인
→ 약 7개월 만에 재거래, +2억 2,000만원 (+4.0%)
대지 136㎡(41.1평) · 연면적 209.34㎡(63.3평) · 1990년 · 제2종일반주거
※ 해제신고 6건 제외설명
한 지번의 손바뀜을 최신순으로 — 재거래·가격 추이를 한눈에. 건별 신뢰도가 다를 수 있습니다.
area_scan — 구/동 실거래가 최신 시세 확인사용방법
/area-scan 성수동1가 # 동: 시세 통계 + 개별 거래
/area-scan 성동구 # 구: 구 전체 통계 + 동별 평단가 순위결과물 — 동을 조회한 최근 한 분기(3개월) 예시입니다.
[성동구 성수동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(모수 분해)를 함께 봐야 표본이 대표성을 갖는지 판단할 수 있습니다.
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가 3*처럼 마스킹해 공개합니다. 이 도구들은 건축물대장
표제부(건축년도·연면적·대지면적)로 역매칭해 '이 건물'이라고 특정하는데, 매칭 신뢰도는
그 특정이 얼마나 확실한지를 뜻합니다.
추정매칭이면 같은 스펙의 옆 건물일 수 있고, 그 값을 고객·보고서에 "이 건물 실거래가"로
인용하면 엉뚱한 건물 가격을 대는 오류가 됩니다.
match_explain은 어떤 표제부 값으로 어떻게 특정했는지(앵커 vs 거래행)를 대조해, 인용 전에
그 위험을 직접 판단하게 합니다.
표기 | 뜻 |
확정 / 정확매칭 | 표제부 값이 정확히 일치 — 사실상 그 필지 |
추정매칭 | 유사 스펙으로 좁힌 것 — 동일 스펙 인접 건물일 수 있습니다 |
인접후보 | 후보 수준 — 확인 없이 인용하지 마세요 |
추정매칭 이하를 고객에게 제시하기 전에 match_explain 으로 근거를 확인하세요.
deal_card_create — 데이터카드건물 사진 위에 실측 수치를 얹은 4:5 카드(2160×2700)를 만듭니다. 홍보 문구는 들어가지 않습니다 — 카드의 모든 글자가 실측값이거나 고정 라벨입니다.
사용방법
/deal-card-image 영등포구 영등포동8가 34-20 [건물사진]직접 호출:
deal_card_create(address="영등포구 영등포동8가 34-20", photo="~/사진.jpg")
결과물 — 건물 사진(입력)에 실측 수치를 얹어 카드(출력)를 만듭니다.
영등포구 영등포동8가 34-20 · 거래일 2026-05-06 · 매매 4.4억 · 토지 7평(평단가 6,377만원/평) · 연면적 9평 · 준공업 · 1985년 준공 · 정확매칭 0.90.
설명
멈추는 지점이 2곳 있습니다 — 둘 다 실패가 아니라 사람이 결정할 상태라 재시도로 뚫리지 않습니다.
LOW_CONFIDENCE — 추정매칭 이하(신뢰도 0.90 미만)는 기본적으로 만들지 않습니다.
카드는 대화를 떠나 고객 손에 가는데, 추정매칭은 정의상 동일 스펙 옆 건물일 수
있는 상태입니다 — 옆 건물 실거래가가 이 건물 값으로 박힌 이미지가 돌아다닐 수
있습니다. match_explain 으로 근거를 확인한 뒤, 그래도 발행하기로 했다면
allow_estimated=true 로 다시 부르세요.
PHOTO_MISSING — 건물 사진이 없으면 만들지 않습니다. 사진 없이 만들면 회색 판이
나가고 결국 다시 만들게 되기 때문입니다. 사진 경로를 주고 다시 부르거나, 그대로
진행하려면 allow_no_photo=true 를 주세요.
그 밖에
매칭 신뢰도가 카드에 배지로 표기됩니다. 위 게이트를 통과해 발행되는 카드에도
근거가 항상 따라다녀야 한다고 봤습니다(추정매칭 이하는 색으로 구분). 즉 신뢰도는
차단(게이트) + 각인(배지) 두 겹으로 다룹니다.
저장 위치는 ~/deal-locator-cards/<날짜>/ 입니다 (DEAL_LOCATOR_CARD_DIR 로 변경 가능).
deals_export — 실거래 CSV 내보내기연월(YYYYMM)을 지정해 서울 전역(또는 한 구)의 상업업무용 통건물 실거래를, 마스킹
지번을 역매칭으로 복원한 CSV로 내려받습니다. DB·분석 파이프라인에 넣을 원천
데이터를 만드는 도구입니다 — 화면 시세 조회는 area_scan 이 담당합니다.
사용방법
/deals-export 202607 → 서울 25개 구 전체, 2026년 7월, 지번 복원(기본)
/deals-export 202601-202606 강남구 → 강남구 상반기(범위는 최대 24개월)
/deals-export 202607 원본 → 역매칭 없이 국토부 원본 그대로(수십 초)직접 호출:
deals_export(year_month="202607"), 범위·구 한정은deals_export(year_month="202601", year_month_to="202606", gu="강남구")
결과물 — 고정 폴더 ~/deal-locator-exports/ 에 복원본 + 미복원본 2파일
(utf-8-sig — 엑셀에서 바로 열립니다. DEAL_LOCATOR_EXPORT_DIR 로 폴더 변경 가능.
날짜 하위폴더가 없어 파이프라인이 경로를 하드코딩해도 되고, 같은 연월 재실행은 같은
파일을 덮어씁니다 — 멱등)
■ 실거래 CSV 내보내기 — 서울전역 202607 (통건물)
복원본: ~/deal-locator-exports/실거래_통건물_서울전역_202607_복원.csv — 171건 (정확매칭 139건 · 추정매칭 32건)
미복원본: ~/deal-locator-exports/실거래_통건물_서울전역_202607_미복원.csv — 31건 (금액·면적은 실측, 지번만 미확정)
전체 202건 · 해제신고 8건 포함(해제사유발생일 컬럼으로 구분)
※ 집합(구분상가) 588건은 취급 범위 밖이라 제외(v1)
구별 상위: 중구 27건 · 종로구 22건 · 강남구 11건 · …/deals-export 2016년부터 강남구, 최근 10년, 2006년부터 전체 처럼 24개월을 넘는
기간을 요청하면, 한 번에 통짜로 받는 게 아니라 연 단위로 나눠 여러 번 호출하고
연도별 파일로 저장합니다. 예를 들어 "2016~2025 강남구"는 아래처럼 진행됩니다.
2016년 → 실거래_통건물_강남구_2016_복원.csv (+ _미복원)
2017년 → …_2017_복원.csv
⋮ (한 해 끝날 때마다 그 해 복원율을 한 줄씩 보고)
2025년 → …_2025_복원.csv
─────────────────────────────────
마무리: 연도별 복원율 표 + 생성된 파일 목록왜 통짜가 아니라 연 단위로 쪼개나요 (기술적 이유)
도구 한 번 호출은 최대 24개월입니다. 한 호출이 유한 시간 안에 끝나야 MCP 클라이언트(예: Claude Desktop)가 응답을 기다리다 타임아웃으로 끊는 사고를 막을 수 있고, 도중 실패해도 그 구간만 다시 받으면 되기 때문입니다(통짜 호출은 몇 시간째 실패하면 전부 날아갑니다).
그래서 연 단위(1~12월) 청크로 끊습니다 — 청크 경계가 연도별 파일과 1:1로 맞아떨어져 DB 파티션·증분 적재에 그대로 쓰기 좋습니다.
첫 해만 오래 걸리고 이후는 빠릅니다. 역매칭이 쓰는 건축물대장은 연도와 무관한 '현재' 대장이라, 첫 해를 처리하며 서울 전 동의 표제부를 받아 캐시에 굳히면 그다음 해들은 거래 조회만 하면 됩니다. 즉 무거운 건 최초 표제부 수신 1회뿐입니다.
이미 받은 해는 다시 긁지 않습니다(멱등 재개). 완결된 과거 연도는 파일이 있으면
건너뛰고, 현재 진행 중인 해만 매번 다시 받아 새로 공개된 월을 반영합니다
(현재 해도 _YYYY_ 파일명으로 고정돼 매달 같은 파일을 덮어씁니다 — 겹치는 파일이
쌓여 파이프라인이 중복 적재하는 일을 막습니다).
그래서 알아둘 것
첫 전체 백필은 오래 걸립니다. 서울 전역 장기이면 표제부 최초 수신 때문에 수십 분
이상 걸릴 수 있어, 시작 전에 안내합니다. 급하면 특정 구부터 받거나 원본(match=false,
역매칭 생략)으로 빠르게 받을 수 있습니다.
과거로 갈수록 지번 복원율이 떨어집니다 — 위에서 설명한 표제부 '현재 스냅샷' 한계
때문입니다(최근 ~84% → 10년 전 ~79% → 20년 전 ~16%). 연도별 복원율 표를 함께
드리니, 어느 연도부터 지번 레이어가 촘촘해지는지 보고 판단하세요. 점(지번) 레이어는
최근·정확매칭 위주로, 과거·미복원·추정은 동 단위 집계 레이어로 쓰는 걸 권합니다.
파일 구성
복원본(…_복원.csv) — 지번이 특정된 거래. 국토부 원본 컬럼(마스킹 지번 포함)은
그대로 두고 복원지번 · 대지위치_표제부 · 도로명대지위치_표제부 · 매칭단계 ·
매칭신뢰도(정확매칭/추정매칭) 컬럼을 추가합니다. 추정매칭은 동일 스펙 인접
건물일 가능성이 있으니 하류에서 매칭신뢰도 로 필터하세요.
미복원본(…_미복원.csv) — 지번 특정에 실패한 거래(역매칭실패사유 포함).
금액·면적은 실측값이므로 버리지 말고 용도에 맞게 쓰세요. 0건이면 파일을 만들지
않습니다.
알아둘 것
통건물(유형='일반')만 담깁니다. 집합(구분상가)은 취급 범위 밖(v1)이라 빠지고 제외 건수만 보고합니다.
해제신고 거래는 행으로 남습니다. 데이터 다운로드가 행을 지우면 원본과 어긋나기
때문입니다 — 시세 분석 전에 해제사유발생일 컬럼이 채워진 행을 제외하세요.
역매칭은 동별 건축물대장 전체를 받습니다 — 콜드 캐시면 수 분~수십 분, 한 번
받은 뒤에는 수 분 안에 끝납니다. 빠르게 원본만 필요하면 match=false(원본).
조회 창(months)은 당월부터 셉니다 (v1.5.0~). months=12 면 '이번 달 포함
최근 12개월'입니다. v1.4.0 까지는 직전 달부터 세어 당월 거래가 통째로 안 보였습니다
— 실측으로 1,200억 거래가 체결 5일 뒤에도 [NOT_FOUND] 였습니다.
당월은 신고기한(계약일로부터 30일)이 안 지나 표본이 얇습니다 — 지금 0건이어도 '거래가 없었다'는 뜻이 아닙니다. 조회 결과에 그 취지의 고지가 함께 나갑니다.
최근 월은 신고 지연(신고기한 30일)으로 데이터가 아직 없을 수 있습니다 — 이때는
[NOT_FOUND] 로 답하며 수치를 지어내지 않습니다.
확보 가능 기간은 2006년 1월 ~ 현재(약 20년)입니다. 그 이전은 원천 데이터가 없습니다(아래 FAQ). "2006년부터", "최근 10년", "전체" 같은 장기 요청은 스킬이 연 단위 파일로 나눠 확보합니다.
장기 데이터는 과거로 갈수록 지번 복원율이 떨어집니다 — 표제부가 '현재 스냅샷'이라
그 사이 재건축된 과거 건물은 못 맞춥니다(실측: 최근 ~84%, 10년 전 ~79%, 20년 전 ~16%).
히스토리 맵을 만든다면 점(지번) 레이어에는 매칭신뢰도=정확매칭만 쓰고, 미복원·
추정매칭은 동(洞) 단위 집계 레이어로 쓰는 걸 권합니다(금액·면적·법정동은 전 기간 실측).
Q. 아파트도 되나요?
아니요. 서울 · 상업업무용 · 매매만 다룹니다(v1). 아파트 · 오피스텔 · 단독다가구 · 토지 · 전월세는 범위 밖입니다.
Q. 첫 조회가 너무 느립니다.
건축물대장 전체를 불러오기 때문에 수십 초~수 분 걸립니다. 이후 15분간 캐시되어 같은 구 조회는 즉시 나옵니다.
Q. 실거래가는 몇 년치까지 받을 수 있나요?
2006년 1월 ~ 현재, 약 20년치입니다. 실거래가 신고 의무화가 2006년 1월 1일 시행돼, 그 이전 거래는 신고 자체가 없어 국토부에 원천 데이터가 존재하지 않습니다(도구 하한도 2006 —
200512는PARSE_ERROR로 거부). 이 도구가 다루는 상업·업무용 통건물 매매도 2006년부터 제공됩니다.다만 이건 원천 데이터가 20년치라는 뜻이고, 마스킹 지번 복원(역매칭)은 최근일수록 강하고 과거로 갈수록 급락합니다(최근 ~84% → 10년 전 ~79% → 20년 전 ~16%). 표제부(건축물대장)가 '현재 스냅샷'이라, 그 사이 재건축·신축된 과거 건물은 현재 대장과 스펙이 안 맞기 때문입니다. 그래서 장기 히스토리 맵을 만든다면 지번 단위 레이어는 최근 구간에서 촘촘하고, 과거 구간은 동 단위 집계(거래밀도·평단가 추이) 로 쓰는 게 맞습니다 — 미복원 건도 금액·면적·법정동은 전 기간 실측이라 동 레이어엔 온전히 활용됩니다.
2006년 이전 시계열까지 필요하면 실거래가가 아닌 다른 소스(감정원 시세지수, 공시지가 이력 등)를 별도 레이어로 붙이는 방법을 검토하세요.
Q. 계약 취소된 거래도 포함되나요?
아니요. 해제신고 건은 집계에서 제외하고 그 건수를 알려줍니다.
Q. 지번이 특정되지 않는 거래가 있습니다.
표제부와 일치하는 필지를 못 찾은 경우입니다.
area_scan결과에마스킹 미복원으로 표기되며, 그 건의 금액·면적은 실측값이지만 주소는 확정된 것이 아닙니다.
Q. 인증키를 설정 파일에 넣기 싫습니다.
실행 폴더(또는 그 상위 1단계)에
.env를 두면 자동으로 읽습니다(.env.example참고)..env는 절대 커밋하지 마세요.보안상
DEAL_LOCATOR_*와DATA_GO_KR_API_KEY만 읽습니다..env의 다른 줄은 무시합니다 — 남의 프로젝트 폴더에서 서버를 띄웠을 때 그쪽 설정(프록시 등)이 섞여 들어와 요청이 엉뚱한 서버를 경유하는 일을 막기 위함입니다.저장·캐시 폴더 설정(
DEAL_LOCATOR_CARD_DIR·DEAL_LOCATOR_EXPORT_DIR·DEAL_LOCATOR_CACHE_DIR)은 실행 폴더의.env에서는 읽지 않습니다. 환경변수,DEAL_LOCATOR_ENV_FILE로 지정한 파일, 홈 설정 파일(~/.deal-locator.env·~/.config/deal-locator/.env)에서만 받습니다 — 남이 만든 폴더의.env가 캐시 폴더를 바꿔, 조작된 데이터를 실측값처럼 읽게 만드는 일을 막기 위함입니다.
Q. 카드 만들 때 임의 파일이 읽히지 않나요?
photo는 파일 내용으로 이미지 여부를 판별합니다(PNG·JPEG·GIF·WebP). 이미지가 아니면 렌더하지 않고 멈춥니다. 카드 렌더는 JavaScript 를 끈 상태로 돌고 모든 네트워크 요청이 차단되므로, 카드 값에 스크립트가 섞여도 실행되지 않고 외부로 나가지도 않습니다.
deal-locator-mcp/
├─ src/deal_locator/
│ ├─ server.py MCP 서버 — 도구 7종 정의 · 구조화 출력
│ ├─ core/ 매칭 엔진 (표제부 역매칭 · 부속지번 · 파이프라인)
│ └─ render/ 데이터카드 렌더 (템플릿 + Pretendard 폰트)
├─ tests/ 114개
├─ server.json MCP 레지스트리 메타데이터
└─ .env.example이 도구가 무엇을 못 하는지를 먼저 밝힙니다. 수치를 인용하기 전에 반드시 함께 읽으세요.
취급 범위
서울 · 상업업무용 · 매매뿐입니다 (v1). 아파트 · 오피스텔 · 단독다가구 · 토지 · 전월세, 그리고 서울 외 지역은 조회되지 않습니다.
통건물(일반)만 다룹니다 — 집합(구분상가) 거래는 모든 응답에서 제외됩니다. 여기서 나오는
시세 · 평단가는 전부 통건물 기준이며, 구분상가 한 칸 시세로 인용하면 안 됩니다. 제외된
집합 거래 건수는 응답의 jiphap_excluded 로 함께 알려줍니다.
매칭의 한계
매칭은 확률이지 등기부가 아닙니다. 추정매칭 은 동일 스펙 인접 건물일 수 있고,
인접후보 는 확인 없이 인용하면 안 됩니다. 추정매칭 이하는 match_explain 으로 근거를
확인한 뒤 쓰세요.
특정되지 않는 거래가 있습니다. 표제부와 일치하는 필지를 못 찾으면 마스킹 미복원 으로
표기됩니다 — 그 건의 금액 · 면적은 실측값이지만 주소는 확정된 것이 아닙니다.
왜 100% 매칭은 불가능한가 (면적 오차의 원인). 매칭은 표제부의 연면적 · 대지면적 · 건축년도(사용승인일) 를 실거래 신고행과 대조하는데, 이 값들은 서로 다른 공부(건축물대장 vs 토지대장)에서 나오기 때문에 완전히 일치하지 않을 수 있습니다.
대지면적이 공부마다 다릅니다. 코너 필지의 가각전제, 도로 확폭 · 건축선 후퇴가 있으면 실제 건축에 쓸 수 있는 땅이 줄어 토지대장 대지면적과 건축물대장 대지면적이 어긋납니다. 또 필지가 여러 지번으로 합필된 경우 주지번 하나만으로는 면적이 맞지 않아 — 이 도구는 부속지번(보조지번) 대장을 합산해 대표지번으로 재앵커하고, 다필지로 확인되면 대지면적 허용 오차를 완화해 보정합니다.
연면적도 공부상 차이가 있습니다. 옥탑 등 일부 공간이 대장에 반영되지 않는 경우가 있어 신고 연면적과 표제부 연면적이 딱 떨어지지 않을 수 있습니다.
그래서 이 도구는 면적 오차를 단계적으로 허용하는 매칭 파이프라인을 씁니다:
마스킹 자릿수 프리필터 — 마스킹 2**는 "본번이 정확히 3자리이고 2로 시작"을
뜻합니다(실측 규칙). 자릿수까지 검사해 후보 풀을 좁혀 오매칭 여지를 줄입니다.
정확매칭 — 연면적 · 대지면적 · 건축년도 3속성 완전일치(사실상 확정)
건축년도 + 연면적 일치
오차범위 ±10%(연면적 · 대지) — 합필 필지는 대지 검사 완화
지분거래 비율매칭 — 지분 매매는 신고 면적이 건물 전체가 아니라 지분 몫이라 절대값 비교가 원리상 불가능합니다. 대신 연면적 지분율 ≈ 대지면적 지분율(등기 지분율은 두 면적에 동일하게 적용됨)이 0.2% 이내로 일치하는 후보가 유일할 때만 복원합니다. 지분거래가 작은 건물의 전체 스펙과 우연히 겹쳐 생기던 오매칭도 함께 차단됩니다.
추정매칭(전부 유일후보 한정) — 건축년도 결측 시 연면적(+대지) 정확일치, 건축년도 ±1년(연말 준공 · 이월 등기 노이즈) + 연면적 정확일치, 대지 공부 오차 시 연면적±10% + 건축년도 일치 등 — 어느 경우든 후보가 유일할 때만 복원. 후보가 둘 이상이면 확정하지 않습니다(옆 건물 오매칭 방지).
위에서 아래로 갈수록 신뢰도를 낮춰 정확매칭 · 추정매칭 · 인접후보로 표기합니다.
매칭 정확도는 표제부 데이터 완전성에 좌우됩니다 — 건축HUB API의 일시 오류로 표제부가 부분 수신되면 그 동의 복원율이 떨어집니다. 이 도구는 5xx 재시도 + 부분수신본 캐시 방지 + JSON/XML 겸용 파싱(건축HUB가 2026-08부터 기본 응답을 JSON으로 변경)으로 항상 완전한 표제부로만 매칭합니다. 대형 동도 절단 없이 수신합니다(신림동 17,795건 실측 대응).
(측정: 서울 25개 구 전수 — 거래 발생 352개 동, 12개월, 통건물 마스킹 매매 2,547건 — 복원율 84.3%(해제 제외 시 84.7%), 확정급 1 · 2단계 68.1%, 합성 자가검증 오매칭 0 — 기준 2026-08 · 표본 기간에 따라 달라짐)
데이터 · 통계
해제신고(계약 취소) 건은 집계에서 제외하고 그 건수를 알려줍니다. 취소된 값을 실거래로 오인하지 않도록 한 조치입니다.
area_scan 통계는 표본이 얇을 수 있습니다. 통건물 매매는 동에 따라 월 1~7건이라, 반드시
coverage(모수 분해: 전체 · 집합 제외 · 해제 제외 · 마스킹 미복원)를 함께 보고 대표성을
판단하세요.
첫 조회는 느리고, 캐시는 최신이 아닐 수 있습니다. 구·동 첫 조회는 건축물대장 전체를 받느라 수십 초~수 분 걸립니다(이후 15분 캐시). 실거래는 매달 갱신되므로 오래된 캐시·프리워밍 데이터는 최신 거래를 반영하지 못할 수 있습니다.
원칙
결과가 없으면 [NOT_FOUND] 를 반환합니다 — 데이터가 없는 것이지 0원이 아닙니다. 이 경우
수치를 지어내면 안 됩니다(AI가 환각하지 못하도록 설계된 신호입니다).
소유자 등 개인정보는 다루지 않습니다. 공개된 실거래 · 건축물대장 실측값만 반환합니다.
위 한계를 넘는 판단(계약 · 감정 · 고객 제시)에는 반드시 원문을 직접 확인하세요. 아래 고지를 함께 읽어주세요.
이 도구의 결과는 참고자료이며 중개대상물 확인·설명서가 아닙니다. 공적장부의 원문(국토교통부 실거래가 공개시스템, 건축물대장)이 언제나 우선합니다. 고객에게 제시하거나 계약 판단에 쓰기 전에 원문을 직접 확인하세요. 매칭 결과의 정확성에 대해 제작자는 책임지지 않습니다.
출처: 국토교통부 실거래가 공개시스템 · 건축HUB (공공데이터포털 data.go.kr)
MIT License — Copyright (c) 2026 디랩스(DLABS)
동봉 폰트 Pretendard 는 SIL Open Font License 1.1 입니다. 폰트에는 MIT 가 적용되지 않습니다 — THIRD_PARTY_NOTICES.md 참조.
디랩스(DLABS) · github.com/syleedlabs
구·동 단위 상업업무용(통건물) 시세 — 동이면 후보 거래까지, 구면 통계·동별 순위.
area 에 구만 주면('강남구') 구 모드, 동을 주면('대치동') 동 모드다. 지번을 몰라도 '동 + 가격대'로 조회한다. 예: area='성수동1가', min_eok_per_pyeong=4.5, max_eok_per_pyeong=5.5 → 연면적 평당 4.5~5.5억 거래를 최신순으로. min/max 가 0 이면 해당 방향 제한 없음. 평당가 기준 = 연면적(거래금액÷연면적평). road_contains(예: '연무장길')를 주면 표제부 역매칭으로 도로명이 특정된 거래만 부분일치 필터 — 도로명 미상(마스킹 미복원) 거래는 제외되며 그 건수를 함께 고지한다. 서울 상업업무용 매매 한정(v1). 첫 조회는 표제부 API 로딩으로 수십 초 걸릴 수 있다. 표본 대표성을 판단할 때는 structuredContent 의 coverage(모수 분해)를 함께 읽을 것.
취급 범위는 통건물(유형='일반')뿐 — 집합(구분상가)은 제외한다(coverage.jiphap_excluded 에 건수). 그러므로 stats 는 전부 '통건물 시세'이며, 상가 한 칸 시세가 아니다.
area 에 구만 주면('강남구'·'강남') 구 모드로 동작한다 — 구 전체 시세와 분기 추이, 그리고 by_dong(동별 대지 평단가 내림차순)을 낸다. 구 모드는 표제부 역매칭을 돌리지 않아 deals 가 항상 비어 있다(scope='구' 로 구분). 개별 지번·거래가 필요하면 동으로 다시 부를 것.
동 평균 평단가는 stats(연면적·대지)에 담긴다 — 가격대·도로명 필터와 무관하게, 표제부 역매칭 이전의 국토부 원본 실거래(통건물, 해제·산출불가 제외)로 산출하므로 전수에 가깝다. '이 동 평단가 시세'를 물으면 deals 가 아니라 stats 를 근거로 답할 것 (deals 는 필터 통과분이라 평균 내면 편향된다). 평균이 필요할 뿐이면 min/max 를 주지 말고(밴드 없이) 호출하면 된다.
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | ||
| limit | No | ||
| months | No | ||
| road_contains | No | ||
| max_eok_per_pyeong | No | ||
| min_eok_per_pyeong | No |
| Name | Required | Description |
|---|---|---|
| area | No | |
| deals | Yes | 최신순. 평단가 기준은 연면적(거래금액 ÷ 연면적평). |
| query | Yes | |
| scope | No | '구' 면 구 전체 통계 모드 — deals 는 항상 비어 있고(역매칭 미실행) by_dong 에 동별 순위가 담긴다. 개별 지번이 필요하면 동으로 다시 조회할 것. |
| stats | No | 동 전체 평단가 시세 — 사용자 가격대·도로명 필터와 무관하게, 표제부 역매칭 이전의 국토부 원본 실거래(해제·산출불가 제외)로 산출. deals(필터 통과분)와 달리 표본이 줄지 않아 평균이 편향되지 않는다. |
| filter | No | 실제 적용된 필터(클램프·스왑 후 값). |
| source | Yes | |
| status | Yes | OK 일 때만 deals 에 실측값이 있다. 그 외에는 수치를 추측·보간하지 말 것. |
| by_dong | No | 구 모드 전용 — 동별 평단가(대지 중앙값 내림차순). 동 모드에서는 빈 배열. |
| message | No | |
| coverage | No | 모수 분해 — matched 만 보지 말고 무엇이 왜 빠졌는지 함께 읽을 것. |
| lookup_status | No | 도메인 원본 상태(거래있음/조건_불일치/거래없음 …) |
| period_months | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent behavior. The description adds context about initialization delay, empty deals in district mode, stats computation from raw data, and reliance on structuredContent for coverage. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with paragraphs and examples, but it is somewhat verbose. The core purpose is front-loaded, but some explanations (e.g., mode details) could be condensed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two modes, multiple filters, output schema with coverage), the description covers all essential aspects: usage scenarios, edge cases, performance characteristics, and how to interpret results. It is sufficiently complete for proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description must entirely explain parameters. It covers area, road_contains, min/max_eok_per_pyeong well with examples. However, limit and months are not explicitly described, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving commercial building market prices by district or neighborhood in Seoul, with two distinct modes (구/동). It distinguishes itself from sibling tools like deal_card_search by focusing on area-based aggregation rather than individual deals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode (district vs. neighborhood) and when to rely on stats vs. deals for accurate averages. It warns about first-query slowness and limitations to '통건물' only. However, it lacks explicit comparison to sibling tools like deal_history or match_explain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
지번 하나로 실거래 데이터카드 PNG 1장(4:5)을 만든다 — 조회부터 이미지까지.
카드에 들어가는 값은 전부 실거래·건축물대장 실측값이다(매매가·토지/연면적· 평단가·용도지역·준공연도·거래일·매도매수). 홍보 문구는 넣지 않는다.
매칭 신뢰도가 카드에 배지로 찍힌다. 이미지가 손을 떠난 뒤에는 대화로 고지할 수 없기 때문이며, '추정매칭' 이하는 색으로 구분된다. 고객에게 내밀기 전에 match_explain 으로 근거를 확인시키는 걸 권한다.
사진이 없으면 렌더하지 않고 PHOTO_MISSING 으로 멈춘다 — 카드는 건물 사진 위에 수치를 얹는 형태라, 사진이 없으면 회색 판이 나가고 결국 다시 만들게 된다. 이때는 재시도하지 말고 사용자에게 사진 경로를 물어볼 것. 사진 없이 진행하기로 사용자가 정하면 allow_no_photo=true 로 재호출한다. eyebrow 로 매매가 위 골드 한 줄을 덮어쓸 수 있다. 기본값은 '<구> 실거래 · YYYY.MM'. '최고가/최저가' 같은 단정 표현은 쓰지 말 것 — 이 도구의 조회 범위(서울 상업업무용·기간 한정) 안에서의 순위일 뿐이라 카드에 박히면 근거 없는 단정이 된다. 저장 위치는 ~/deal-locator-cards/<날짜>/ (DEAL_LOCATOR_CARD_DIR 로 변경 가능).
최초 1회 playwright install chromium 이 필요하다.
| Name | Required | Description | Default |
|---|---|---|---|
| photo | No | ||
| months | No | ||
| address | Yes | ||
| eyebrow | No | ||
| allow_no_photo | No |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| notes | No | |
| photo | No | 카드에 쓴 건물 사진(미지정 시 빈 문자열) |
| price | No | |
| query | Yes | |
| source | Yes | |
| status | Yes | OK 일 때만 out_png 에 카드가 생성됐다. PHOTO_MISSING 은 실패가 아니라 '사람이 결정할 게 남은' 상태 — 사진 경로를 주거나 allow_no_photo=true 로 재호출하면 진행된다. |
| address | No | |
| eyebrow | No | |
| message | No | |
| out_png | Yes | 생성된 카드 PNG 경로(4:5, 2160×2700) |
| confidence | No | |
| confidence_score | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently discloses key behaviors: creation of a PNG (mutation, consistent with readOnlyHint=false), confidence badge rendering, photo requirement causing PHOTO_MISSING failure, and restriction against promotional wording. This adds context beyond the annotations (which only hint at non-readonly and open-world).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise; all sentences add value but the second paragraph could be trimmed. It is front-loaded with the main purpose and key constraints. Minor redundancy in explaining the photo failure mode.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, a non-trivial operation, and the existence of an output schema, the description covers the essential workflow, failure modes, and output type. It lacks explicit return value documentation but the output schema fills that gap. Months parameter explanation is missing, slightly reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It does well for address, eyebrow, and allow_no_photo, but months and photo are only implicitly mentioned (months as '기간 한정', photo as required). The description partially compensates but leaves some parameters insufficiently explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: creating a PNG card (4:5 ratio) with real transaction data from a land lot number. It distinguishes itself from sibling tools like deal_card_search and deal_history by specifying the one-to-one mapping from address to card image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: recommending use of match_explain before presenting the card, handling photo missing by asking user for photo path or allow_no_photo=true, and prohibiting assertive phrases like '최고가/최저가' in the eyebrow. Also notes the one-time prerequisite 'playwright install chromium'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
지번의 실거래 종합카드 1콜 — 최신 매매가·평단가·매도/매수·매칭 신뢰도 + 표제부.
서울 상업업무용 매매 한정. months(160)는 조회 기간(개월).
첫 조회는 표제부·실거래 API를 불러 수십 초수 분 걸릴 수 있다(이후 15분 캐시).
수치를 계산에 쓸 때는 텍스트가 아니라 structuredContent 를 읽을 것
(status='OK' 일 때만 latest 에 실측값이 있다).
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | ||
| address | Yes |
| Name | Required | Description |
|---|---|---|
| notes | No | |
| query | Yes | |
| latest | No | 최신 매칭 거래 1건. status != 'OK' 이면 null. |
| source | Yes | |
| status | Yes | OK 일 때만 latest 에 실측값이 있다. 그 외에는 수치를 추측·보간하지 말 것. |
| address | No | |
| message | No | status != 'OK' 인 사유 |
| building | No | 매칭 앵커가 된 건축물대장 표제부. |
| lookup_status | No | 도메인 원본 상태(거래있음/거래없음/표제부없음 …) |
| period_months | Yes | |
| cancelled_count | No | 제외된 해제신고 건수 |
| transaction_count | Yes | 기간 내 매칭 거래 수(deal_history 로 전체 확인) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description significantly supplements annotations by disclosing that the first call can take tens of seconds to minutes, data is cached for 15 minutes, and structuredContent should be used for calculations with status-dependent fields. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no wasted words, front-loads the main purpose, and provides necessary details in a single paragraph. Could be slightly more structured but remains effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers purpose, usage, parameter range, and behavioral notes. It does not address error handling but is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description explains the months parameter range (1-60) but does not elaborate on the address parameter format or other constraints. Partial compensation for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a real estate comprehensive card for a land parcel number in Seoul commercial business use, listing specific outputs like transaction price, average price, sell/buy, and reliability. While purpose is specific, it does not explicitly distinguish from sibling tools like deal_card_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the geographic and property type limitation (Seoul commercial business only) and mentions first call may be slow with caching after 15 minutes. It does not explicitly exclude alternatives but provides clear context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
지번의 매칭 실거래 이력 전체(최신순) — 각 건에 매칭 신뢰도 표기.
서울 상업업무용 매매 한정. months(1~60) 기본 24개월. 재거래·가격 추이를 계산할 때는 텍스트가 아니라 structuredContent 의 transactions[] 를 읽을 것 (건별 신뢰도가 다를 수 있다).
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | ||
| address | Yes |
| Name | Required | Description |
|---|---|---|
| notes | No | |
| query | Yes | |
| source | Yes | |
| status | Yes | OK 일 때만 transactions 에 실측값이 있다. |
| address | No | |
| message | No | status != 'OK' 인 사유 |
| building | No | 매칭 앵커가 된 건축물대장 표제부. |
| transactions | Yes | 최신순(deal_date 내림차순). 건별 신뢰도가 다를 수 있으니 각 건의 confidence 를 볼 것. |
| lookup_status | No | 도메인 원본 상태(거래있음/거래없음/표제부없음 …) |
| period_months | Yes | |
| cancelled_count | No | 제외된 해제신고 건수 |
| transaction_count | Yes | |
| lowest_confidence_score | No | 이력 중 최저 신뢰도. 이력 전체를 한 덩어리로 인용할 땐 이 값 기준으로 고지할 것 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, idempotent, non-destructive. Description adds: scope (Seoul commercial office), months default, and instruction to read structuredContent for accurate data. No contradiction; description adds useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise with three short sentences covering purpose, scope, parameters, and a critical usage instruction. No fluff; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, description does not need to explain return values. It sufficiently covers scope, parameters, and data usage (structuredContent). Could mention output language or potential pagination, but overall complete for a tool with rich annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 parameters with 0% coverage. Description explains months range (1-60) and default, and that address is a land lot (지번). Adds value beyond schema but could be more detailed on address format or other constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it provides matched real transaction history for a land lot, newest first, with confidence, and specifies scope: Seoul commercial office sales. It distinguishes itself from siblings by its specific data and usage instruction to read structuredContent for trends, but does not explicitly contrast with sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use: for recalculating trends, use structuredContent.transactions[], not text. Also specifies months range (1-60) and default 24. Does not explicitly state when not to use or alternatives, but the structuredContent instruction is a clear guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
최신 매칭의 근거를 투명하게 — 표제부 앵커값 vs 거래행값, 발화 단계, 필지세트.
추정매칭 검증·감사용. 보고서 인용 전 반드시 확인 권장. structuredContent 의 comparison 이 앵커 대 거래행 대조(delta·equal)를 담는다.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | ||
| address | Yes |
| Name | Required | Description |
|---|---|---|
| row | No | 실거래 원본 행(비교 대상). |
| deal | No | 설명 대상 거래(최신 1건). |
| query | Yes | |
| anchor | No | 표제부 앵커(비교 기준). null 이면 지번이 노출된 거래라 스펙 대조 없이 매칭된 것. |
| source | Yes | |
| status | Yes | OK 일 때만 verdict/anchor/row 에 실측값이 있다. |
| address | No | |
| lot_set | No | |
| message | No | status != 'OK' 인 사유 |
| verdict | No | 매칭 판정. confidence_score < 0.90 은 추정 — 공부 대조 전 확정 인용 금지. |
| multi_lot | No | true면 대지면적 비교를 완화해 매칭한 것 |
| anchor_via | No | 직접/부속지번/인접본번 |
| comparison | No | 앵커 vs 거래행 대조. anchor 가 없으면 null. |
| disclaimer | No | |
| anchor_bunji | No | |
| lookup_status | No | |
| period_months | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds that the output contains comparison data in structuredContent, which gives some behavioral context beyond annotations, but does not detail other traits like rate limits or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise but uses technical jargon without explanation. It front-loads the purpose but misses parameter information, making it less efficient in providing complete understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and annotations, the description covers the high-level purpose and output content. However, it fails to explain the parameters, which are essential for correct invocation, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (months, address) with schema_description_coverage 0%. The description does not explain the meaning or usage of either parameter, forcing the agent to infer from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows the basis of matching, comparing anchor values vs transaction row values, utterance stage, and parcel set. It is specific about what it does and mentions use for verification/audit, but does not explicitly distinguish from sibling tools like deal_card_search or deal_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance by stating it is for verification/audit of estimated matching and recommends checking before citing in reports. However, it does not specify when not to use the tool or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
주소 문자열을 구/동/번지 + 법정 코드로 해석하고 필지 구성(부속지번)을 확인한다.
예: '구로구 구로동 1128-1', '서울 성수동2가 321-90' (동만 줘도 구를 역추적). 다른 도구를 쓰기 전 주소가 모호할 때 먼저 호출. lot_structure='조회실패'는 '단일 필지'가 아니라 미확인이다 — 구분해 읽을 것.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| source | Yes | |
| status | Yes | OK 일 때만 해석 결과가 유효하다. |
| address | No | |
| lot_set | Yes | 질의 지번이 속한 대지의 필지세트(대표+부속). lot_structure='조회실패'면 빈 배열 |
| message | No | status != 'OK' 인 사유 |
| bdong_code | No | 법정동 5자리. 조회 실패면 빈 문자열 |
| main_bunji | No | lot_structure='부속지번' 일 때 대표지번 |
| sigungu_code | No | 시군구 5자리. 미상이면 빈 문자열 |
| lot_structure | Yes | 필지 구성. '조회실패'는 '단일'이 아니라 미확인 — 단독 근거로 쓰지 말 것 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations by explaining a key behavioral nuance: lot_structure='조회실패' means unconfirmed, not single parcel. Also explains backtracing capability. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: purpose, examples, usage guidance, and a critical behavioral note—all in 4 lines. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers input format, usage context, and a notable return value nuance. No gaps for the intended functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides examples and format hints for the query parameter, adding essential meaning. Could be enhanced with more detail on allowed characters or structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves address strings into components and checks parcel composition, with concrete examples. It distinguishes from siblings by recommending it as a prerequisite when address is ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'call this first before using other tools when address is ambiguous'. Lacks explicit when-not scenarios, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0area_scandeal_card_createdeal_card_searchdeal_historymatch_explainresolve_addressScored across 6 tools
Each tool has a distinct and well-defined purpose. resolve_address handles address parsing, deal_card_search retrieves the latest deal card for a specific parcel, deal_history provides full transaction history, match_explain details matching logic, area_scan offers area-level statistics, and deal_card_create generates a PNG card. There's no functional overlap.
All tool names follow a consistent verb_noun snake_case pattern (e.g., resolve_address, deal_card_search, area_scan). The naming is predictable and clearly describes each tool's action.
With 6 tools, the server covers the core workflows of a real estate deal locator: address resolution, individual deal lookup, history, matching explanation, area scanning, and card generation. The count feels appropriate for the domain and avoids bloat.
The tool set covers essential operations for locating commercial property deals in Seoul, including address lookup, detailed parcel info, history, matching explanation, and area-wide scanning. A minor gap is the lack of a direct search by specific building name or address beyond the initial resolve, but area_scan with road filter partially addresses this.
Agent-native MCP server over 49M+ US public and government records, privacy-first, always current.
RealEstateAPI MCP — property search, detail, and skip-trace (realestateapi.com)
MCP server giving Claude AI access to 22+ NYC public-record databases for real estate due diligence