Korea Realty MCP Server

지역의 매매 시세를 평형대 4구간(소형/중소형/중형/대형, 전용면적 기준)으로 조회한다. "○○구에서 무슨 평수대가 얼마쯤 해?"류 질문용 — 특정 단지는 realty_search_complexes를 쓰라. 구간 라벨의 평수는 **전용평**이다. 사용자의 분양평 감각으로는 소형<60㎡≈분양 24평 미만, 중소형 60~85㎡≈분양 24~34평, 중형 85~115㎡≈분양 34~47평, 대형 115㎡+≈분양 47평 이상.

유찰이 누적돼 최저입찰가가 크게 떨어진 물건을 찾는다. 유찰이 많다는 건 싸다는 뜻이기도 하지만 권리관계·물건 하자 등 팔리지 않는 이유가 있다는 뜻이기도 하다. 결과를 추천으로 제시하지 말고 확인이 필요한 후보로 제시하라.

경매 사건의 유찰 이력(기일별 최저가 저감 시계열)·가격 변동 이벤트·물건 사진 URL을 조회한다. "몇 번 유찰됐어? 얼마나 떨어진 거야? 사진 있어?"류 질문의 담당 도구. 사진은 법원 원천에서 기일 후 소멸해 **수집 시점 보존본만 존재**한다(국내 공개 API에 드문 축). court_schedule에서 result='유찰'인 행이 유찰 이력, min_bid_10k의 저감이 가격 흐름이다. result가 null인 행은 미래 기일이거나 미해독 법원 코드(result_code 원문 병기)다 — 의미를 지어내지 말고 그대로 전하라. tracking·price_events는 2026-07-23 이후 일일 스냅샷 비교분이라 비어 있을 수 있다(비어 있음 ≠ 변동 없음, court_schedule이 정본).

"이 지역 이 물건은 보통 감정가의 몇 %에 낙찰되나"를 실제 매각결과로 답한다. 입찰가를 정할 때 쓰는 핵심 지표다. `by_fail_count`에 유찰 횟수별 분포가 들어 있어 "2회 유찰된 물건은 보통 몇 %에 낙찰되는가"를 바로 읽을 수 있다. 낙찰가율 = 낙찰가 / 감정가 × 100. 100%를 넘으면 감정가보다 비싸게 팔린 것이다.

경매 물건의 최저입찰가를 같은 단지 실거래 시세와 대조해 할인율·표면수익률을 낸다. 주소·단지명 정규화 정확매칭으로 붙이며, 감정가가 시세의 50~150% 범위인 건만 비교한다 (지분경매·특수물건을 배제하기 위함). 결과의 `signal`은 주의/관심/보통/낮음 판정이다. ⚠️ 시세 기준은 해당 단지의 **전 평형 혼합 평균**이고 경매 물건의 전용면적과 매칭되지 않았다 — 소형 물건 vs 대형 혼합 평균이면 할인율이 부풀 수 있다. 큰 할인율·signal은 면적 확인 전에는 단정하지 말 것. 이 도구는 다른 도구보다 느리다(1~2초).

[유료] 여러 지역의 매매·전세 시세와 추이를 나란히 비교한다. 갈아타기·투자처 비교용.

특정 단지·특정 평형의 **최근 6개월 매매 실거래**를 건별(계약일·층·가격)로 조회한다. 평형별 시세 요약만 필요하면 realty_search_complexes의 prices_by_area로 충분하다. 평수는 pyeong_supply(분양)·pyeong_exclusive(전용) 중 사용자가 쓴 쪽에 넣어라 — 하나는 필수. 이 도구는 매매 전용이다 — 전월세는 realty_complex_rent_by_pyeong을 쓴다.

단지의 평형별 전세 보증금·월세 중앙값을 조회한다. 전세가율(전세÷매매) 계산의 전세 축이다. complex_key·complex_name 중 하나는 필수. 부분일치는 동명 단지가 섞일 수 있으니 가능하면 realty_search_complexes로 complex_key를 먼저 특정하라. 행 키 supply_pyeong은 **분양평**(전용㎡ ÷ 3.305 ÷ 0.745 반올림) 기준이다.

[유료] 단지 하나의 시세·전세·기본정보를 통합 조회한다. 응답에 좌표(latitude/longitude)와 complex_key가 들어 있다 — 이어서 realty_poi_nearby(입지)·realty_predict_price(예측)에 그대로 넣어 심층 분석하라.

지역 인구통계를 조회한다 — "인구 줄고 있어?", "1인 가구 비율은?", "고령화 심해?", "순유입 되는 동네야?"류 질문용. 응답 meta.data_as_of가 실제 최신 시점이다 — warning이 있으면 그대로 사용자에게 전달하고, 밀린 수치를 "지금 인구"로 단정하지 말 것. 연간 계열(households·age)은 기준연도를 밝혀라. households만 동명 시군구(중구·서구 등)를 거절한다(원천 단명 수집 결함) — 그 경우 population·migration(정식 명칭 수집)으로 대신 조회하라.

사건번호로 경매 물건의 상세를 조회한다. 사건번호는 법원 간 유일하지 않다(전국 평균 2.8개 법원에서 중복). court_name을 생략하면 중복 시 오류와 함께 후보 법원 목록이 돌아오니, 그걸 보고 법원을 지정해 다시 호출하라. `rights` = 매각물건명세서 핵심(최선순위 설정·인수되는 권리 원문·위험 플래그·배당요구종기). 이것은 법원 공시의 전달이지 권리분석 판단이 아니다 — 답할 때 rights.disclaimer를 함께 전하고, 등기부·임차인 현황 전체가 아님을 밝혀라. rights가 null이면 명세서 미수집 상태(rights_note에 사유)이므로 권리관계를 절대 지어내지 말 것. 유찰 이력·기일별 저감·사진은 realty_auction_history가 담당이다.

[유료] 지역의 투자 위험도를 변동성·유동성·공급압력 축으로 점수화한다. 응답의 disclaimer(통계 요약이며 투자 권유 아님)를 사용자에게 반드시 함께 전달하라.

단지의 학군(v5)·교통(지하철·버스) 점수를 조회한다 — "이 아파트 학군 어때? 역세권이야?" 담당. complex_key/complex_name이면 단지 점수, region만 주면 지역 집계+축별 상위 5 단지. 학군 점수는 학원가 강도+군집 보정의 **스크리닝 지표**다 — 학원가 데이터가 시 단위라 도심 외곽 면/읍이 다소 높게 나올 수 있고, 학교 배정·수준 판단이 아니다(그렇게 팔지 말 것). subway_distance_m는 최근접역 직선거리(도보 거리 아님). 점수 미산정 단지는 not_found가 정직한 답이다 — 지어내지 말고 realty_search_complexes로 단지 실존부터 확인하라.

한국 기준금리·KOSPI·M2, 미 연준금리·S&P500 등 거시 지표의 월별 시계열을 조회한다. "금리가 집값에 어떤 영향?"류 배경 분석용. ⚠️ 이 데이터는 원천 수집이 멈춰 있을 수 있다 — 응답 meta.data_as_of가 실제 최신 시점이다. 밀린 데이터를 "지금 금리"로 인용하지 말고 반드시 시점을 함께 밝혀라.

[유료] 미분양 추이와 시장심리지수를 한 번에 조회한다. 매수 타이밍 판단의 거시 신호.

빌라(다세대·연립)·오피스텔·단독주택·토지의 실거래 **매매가**를 조회한다 — 아파트 밖 질문의 1차 도구. 응답 = 최근 거래(recent) + 집계(stats: 표본 수·가격·상위 구성). **매매 데이터만 있다** — 전월세를 물으면 이 축엔 데이터가 없다고 답하라(추정 금지). 면적 기준: villa/officetel은 전용면적(area_m2·area_pyeong), house는 대지(land_*)와 건물(building_*) 분리, land는 계약면적·지목(land_category)·용도지역(zoning)이 온다. land의 share_type='지분' 행은 필지 일부 거래라 면적당 가격 비교에 쓰지 말 것(집계는 지분·해제 제외 — 응답 note 참조). 아파트는 realty_region_price_stats·search_complexes 담당.

[유료] 좌표 주변의 지하철·학교·병원·마트 등 입지 요소를 거리순으로 조회한다. 단지 좌표는 realty_complex_report가 준다. "역세권인가", "초품아인가" 판단용.

[유료] 시군구별 병원·학교·지하철역 개수 통계를 조회한다. 지역 간 인프라 비교용. 지역 키는 '시도축약 시군구' 2토큰이다(예: '서울 마포구', 세종은 1토큰). 병원·지하철은 수집 범위가 수도권·광역시 중심이라 지방 시군구는 0으로 나올 수 있다 — 0을 "없다"로 단정하지 말고 수집 범위 밖일 수 있다고 말하라.

[유료] 아파트 단지의 향후 가격을 XGBoost 모델로 예측한다. complex_name 또는 complex_key 중 하나는 필수. 동명 단지가 여러 지역에 있으면 먼저 realty_complex_report로 단지를 특정한 뒤 complex_key로 호출하라. 응답의 disclaimer(모델 정확도·백테스트 성적)를 사용자 답변에 반드시 함께 전달하라 — 예측은 참고 지표이지 투자 보장이 아니다.

아파트 청약(분양) 공고를 조회한다 — 분양가·청약 접수 일정·당첨자 발표일·입주 예정·위치. "다음 달 청약 넣을 만한 데 있어?", "○○에 분양하는 아파트 있어?"류 질문용. price_min/price_max는 주택형별 분양 최고가의 최소·최대(만원)다 — 한 공고에 여러 주택형(house_type_count)이 있다. 청약 자격·가점은 이 데이터에 없다(지어내지 말 것).

[유료] 건령·거래활성 기반 재건축 **후보 스크리닝** 상위 단지를 조회한다. 점수 = 건령(최대 70, 30년 연한 기준) + 최근 12개월 거래활성 전국 백분위(최대 30). 사업성(용적률·대지지분·안전진단·조합 단계)은 반영되지 않는다 — 후보 발굴용이지 투자 판단 근거가 아니며, 응답의 disclaimer를 사용자에게 그대로 전하라. (구버전 점수 포화로 2026-07-30 보류했다가 산식 v2 재계산 검증 후 재개 — DATA-060)

[유료] 서울시 정비사업(재개발·재건축·가로주택 등) 사업장 목록 — 사업명·유형· 진행 단계·위치. "○○구 재개발 어디까지 진행됐어?"류 질문용. **커버리지는 서울 한정**(정보몽땅 원천) — 타 시도는 이 도구로 답할 수 없다고 밝혀라. 세대수·준공예정은 원천 목록이 제공하지 않아 null이다(지어내지 말 것). 진행 단계 필터는 미지원 — 결과의 stage 필드(한글: 조합설립인가·관리처분인가 등)로 판별하라. 재건축 **유망도 점수**는 이 도구가 아니라 realty_reconstruction이 담당한다.

지역의 아파트 실거래 시세 추이를 조회한다. 경매가가 싼지 판단하는 기준선이 된다. region은 시군구명(예: '강남구'). 동명 시군구가 여러 시도에 있으면 '서울특별시 중구'처럼 시도를 앞에 붙여라. metric: price(매매) | rental(전월세). **rental은 추이가 아니라 최신월 스냅샷**(전세 중앙·평균, 월세 보증금·월세, 전세비중)을 돌려주고 months는 적용되지 않는다 — 전월세 월별 추이는 백엔드에 없다(2026-07-30 실측). 추이가 필요한 질문엔 price만 가능. 평수는 둘 중 사용자가 쓴 쪽에만 넣는다: - pyeong_supply: 분양평수(공급면적). 흔히 말하는 "34평"이 이것이다 — 내부에서 ×0.745로 환산한다. - pyeong_exclusive: 전용면적 기준 실평수. 이 데이터의 원래 기준이다.

지역(시군구) 순위를 조회한다 — "제일 비싼 동네 어디야?", "요즘 많이 오른 지역은?", "전세가율 높은 곳은?"류 질문용. price=거래량 가중 전용 평당가(최소 5건, 최신월은 집계 진행 중일 수 있음) · growth=전용 60-85㎡ 고정 YoY(평형 구성 왜곡 제거) · investment=전세가율/갭투자 금액 · transit/school=단지 점수의 시군구 평균. 응답 methodology의 산식·단위를 답변에 반영하라.

[유료] 시군구별 월세 수익률·평균 매매가·평균 월세를 조회한다. 수익형 투자 스크리닝용.

법원경매 물건을 지역·종류·감정가·유찰횟수로 필터링해 조회한다. 감정가(min_price_10k/max_price_10k)는 **만원** 단위다 — 5억은 50000. 유찰이 많을수록 최저입찰가가 감정가 대비 낮아진다(`min_bid_rate`가 그 비율). ⚠️ **최저입찰가는 출처를 반드시 확인해라** — 건별 `min_bid_source`가 붙는다. · `court_schedule` — 법원 기일표 정본이다. 그대로 믿어도 된다(활성의 28.8%). · `item_list` — 물건목록값이다. 유찰이 있으면 **저감 한 단계만큼 낡아 실제보다 높을 수 있다**(2026-08-04 실측: 유찰 1회 이상에서 정본과 3%만 일치, 25~43% 과대). 이 경우 `min_bid_note`가 함께 온다. 사용자에게 단정적으로 말하지 말고 그 한계를 전해라. 저감률로 역산해 추정하지 마라 — 재감정으로 최저가가 **오르는** 사건도 있다. 응답의 `min_bid_stale_risk_count`가 그 페이지에서 낡았을 수 있는 건수다. 회차별 정확한 가격은 realty_auction_history의 court_schedule에 있다. 목록에는 요약 필드만 담긴다. 특정 물건의 전체 정보(면적·법원 계·주소 상세 등)는 돌아온 id로 realty_get_auction_case를 호출해 받아라.

아파트 단지를 이름·지역으로 검색하고 **평형별 실거래 시세**를 함께 돌려준다. "○○아파트 34평 얼마야"류 단지 질문의 1차 도구다. query·region 중 하나는 필수. prices_by_area가 평형별 시세다 — pyeong_exclusive(전용평)와 pyeong_supply_est(분양평 어림)를 병기하므로, 사용자가 말한 "34평"(보통 분양평)은 pyeong_supply_est로 맞춰 답하라. 단지 수준 avg_price는 전 평형이 섞인 평균이니 평수 질문에 쓰지 말 것. 응답의 complex_key는 realty_complex_rent_by_pyeong·[유료] 단지 도구들에 그대로 넣는 키다.

search가 돌려준 id로 경매 사건의 전체 내용을 가져온다. id 형식은 "법원명|사건번호" (예: "서울동부지방법원|2025타경51727"). 사건번호는 법원 간 중복되므로 법원명 없이 조회하면 후보 목록이 돌아올 수 있다. rights(매각물건명세서 요약)가 있으면 법원 공시의 전달로만 인용하고, 없으면(rights_note 참조) 권리관계를 지어내지 말 것 — 권리분석 판단은 이 도구의 데이터 밖이다.

이 서버가 준 데이터로 만든 답이 틀렸을 때 신고한다. 사용자가 "그거 틀렸다", "이상하다", "숫자가 안 맞는다"고 하면 **먼저 이 도구를 호출한 뒤** 정정 답변을 하라. 신고는 서버 운영자에게 전달되어 실제 수정에 쓰인다. 사용자가 지적하지 않았는데 추측으로 부르지는 말 것.

법원경매 물건을 자연어로 검색한다. 지역·물건종류·유찰횟수·감정가를 질의에서 뽑아 필터링한다. 예: "서울 강남구 아파트", "유찰 2회 이상인 경기도 오피스텔", "서울 아파트 감정가 5억 이하". 이 파서는 최소 어댑터라 못 쓰는 축(면적·기일·층 등)이 있다. 못 쓴 조건은 응답의 `unapplied_conditions`에 적히므로, 그게 비어 있지 않으면 결과 범위를 좁게 오인하지 말고 `realty_search_auctions`로 조건을 직접 지정해 다시 조회하라. 각 결과의 id는 이어서 fetch(id)에 그대로 넣으면 상세를 볼 수 있다.