# korea-realty — 한국 부동산 데이터 MCP 서버

[![MCP Badge](https://lobehub.com/badge/mcp/sallim-app-korea-realty)](https://lobehub.com/mcp/sallim-app-korea-realty)

법원경매·국토교통부 실거래·청약 공고 원문·대출/세금 계산을 **AI가 조회할 수 있는 도구**로 내보내는
MCP 서버입니다. Claude·ChatGPT·Cursor 같은 클라이언트에 붙습니다.

```
https://realty.sallim.app/mcp     ← 설치·가입·API 키 없이 이 주소만 등록하면 됩니다
```

## ⚠️ 먼저 읽을 것 — 이 코드만으로는 데이터가 안 나옵니다

이 저장소는 **서버 코드**이고, 도구들은 우리 비공개 데이터 API(경매·실거래 원장)를 호출합니다.
그래서 clone해서 그냥 띄우면 **거의 모든 도구가 실패합니다**. 없는 것을 있는 척하지 않기 위해
먼저 적습니다. 쓰는 길은 둘입니다.

1. **원격 주소로 붙기(권장)** — 위 URL을 클라이언트에 등록하면 우리 서버가 응답합니다.
   키 없이 하루 30콜, 이메일만 넣는 무료 사전등록으로 100콜.
2. **자기 백엔드를 붙이기** — `.env.example`의 `REALTY_BACKEND_URL`을 자기 데이터 API로
   바꾸고, 그 API가 이 서버가 기대하는 응답 모양을 내면 동작합니다(계약은
   `docs/backend-traps.md`에 실측으로 적혀 있습니다).

## 붙이는 방법

**Claude 데스크탑·웹** — 설정 → 커넥터 → 커스텀 커넥터 추가 → 이름 `korea-realty`,
URL에 위 주소.

**Claude Code / Codex CLI**
```bash
claude mcp add --transport http korea-realty https://realty.sallim.app/mcp
```

**ChatGPT** — 설정 → 커넥터 → 커스텀 커넥터(요금제에 따라 메뉴가 없을 수 있습니다).

## 도구

무료 45종 + 유료 10종입니다. **`tools_paid.py`가 없으면 그게 무료판입니다** — 파일 부재가
곧 비활성이고, 별도 플래그가 없습니다(이 저장소에는 그 파일이 없습니다).

| 축 | 예 |
|---|---|
| 법원경매 | 물건 검색·사건 상세·기일별 저감 이력·낙찰가율·시세 대비 할인율 |
| 실거래·시세 | 지역/단지/평형별 시세, 전월세·전세가율, 비아파트(빌라·오피스텔) |
| 청약 | 공고 목록·**공고 원문 팩트**(전매제한·중도금·층별 분양가표)·경쟁률·가점 커트라인 |
| 규범·계산 | 대출 한도·DSR·스트레스 금리, 양도세 시나리오, 취득세·규제지역, 정비사업 지위양도 |
| 그 외 | 인구통계, 입지 점수(학군·교통), 지역 순위, 거시지표 |

### 전체 도구 목록 (55종)

디렉토리·크롤러가 읽는 자리다. 라이브 `tools/list` 응답에서 생성했다 — 값이 궁금하면 `curl -s -X POST https://realty.sallim.app/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'` 로 직접 확인하면 된다.

| 도구 | 하는 일 |
|---|---|
| `fetch` | search가 돌려준 id로 경매 사건의 전체 내용을 가져온다. |
| `realty_area_price_bands` | 지역의 매매 시세를 평형대 4구간(소형/중소형/중형/대형, 전용면적 기준)으로 조회한다. |
| `realty_auction_alerts` | 유찰이 누적돼 최저입찰가가 크게 떨어진 물건을 찾는다. "○○에서 유찰 많은 물건"은 |
| `realty_auction_history` | 경매 사건의 유찰 이력(기일별 최저가 저감 시계열)·가격 변동 이벤트·물건 사진 URL을 |
| `realty_auction_sale_rate` | "이 지역 이 물건은 보통 감정가의 몇 %에 낙찰되나"를 실제 매각결과로 답한다. |
| `realty_public_rental_notices` | 공공임대 모집공고 — LH 행복주택·국민임대·매입임대·전세임대 등 지금 모집 중인 공고와 원문 주소. 지방공사(SH·GH) 공고는 원천 밖이라고 함께 알린다. |
| `realty_builder_presale_record` | 시공사·시행사별 분양 성적 — 공고 수·공급 세대·무순위(줍줍) 세대와 비율·청약 1순위 배수·미달 세대. |
| `realty_capital_gains_tax` | 선언된 양도가·취득가·필요경비·보유기간에 **양도소득세 세율표를 결정론으로 적용**한다 |
| `realty_compare_auction_vs_market` | 경매 물건의 최저입찰가를 같은 단지 실거래 시세와 대조해 할인율·표면수익률을 낸다. |
| `realty_compare_regions` | [유료] 여러 지역의 매매·전세 시세와 추이를 나란히 비교한다. 갈아타기·투자처 비교용. |
| `realty_complex_pyeong_price` | 특정 단지·특정 평형의 **최근 6개월 매매 실거래**를 건별(계약일·층·가격)로 조회한다. |
| `realty_complex_rent_by_pyeong` | 단지의 평형별 전세 보증금·월세 중앙값을 조회한다. 전세가율(전세÷매매) 계산의 전세 축이다. |
| `realty_complex_report` | [유료] 단지 하나의 시세·전세·기본정보를 통합 조회한다. |
| `realty_demographics` | 지역 인구통계를 조회한다 — "인구 줄고 있어?", "1인 가구 비율은?", "고령화 심해?", |
| `realty_get_auction_case` | 사건번호로 경매 물건의 상세를 조회한다. |
| `realty_invest_risk` | [유료] 지역의 투자 위험도를 변동성·유동성·공급압력 축으로 점수화한다. |
| `realty_loan_eligibility` | **"내 조건이면 어떤 대출을 쓸 수 있나"**를 상품별로 나란히 낸다 — 사용자가 어느 규칙 토픽을 |
| `realty_loan_limit` | 선언된 조건(지역·시가·차주 유형·소득)에 대해 **주담대 규제 상한**을 결정론으로 |
| `realty_location_scores` | 단지의 학군(v5)·교통(지하철·버스) 점수를 조회한다 — "이 아파트 학군 어때? 역세권이야?" |
| `realty_macro_indicators` | 한국 기준금리·KOSPI·M2, 미 연준금리·S&P500 등 거시 지표의 월별 시계열을 조회한다. |
| `realty_market_signals` | [유료] 미분양 추이와 시장심리지수를 한 번에 조회한다. 매수 타이밍 판단의 거시 신호. |
| `realty_member_transfer_check` | 투기과열지구에서 재건축·재개발 물건을 **지금 사면 조합원 지위를 승계받을 수 있는지**를 |
| `realty_move_in_supply` | 지역의 입주 예정 물량을 연월별로 집계한다 — "○○ 입주장 리스크 있어?", "내년에 |
| `realty_nonapt_prices` | 빌라(다세대·연립)·오피스텔·단독주택·토지의 실거래 **매매가**를 조회한다 — 아파트 밖 |
| `realty_notice_facts` | 입주자모집공고 **원문**에서 추출·검증한 팩트시트 — 전매제한·재당첨제한·거주의무· |
| `realty_notice_text` | 입주자모집공고문 원문을 쪽 단위로 읽는다 — 팩트시트에 없는 세부(특별공급 소득·자산 기준, |
| `realty_poi_nearby` | [유료] 좌표 주변의 지하철·학교·병원·마트 등 입지 요소를 거리순으로 조회한다. |
| `realty_poi_stats` | [유료] 시군구별 병원·학교·지하철역 개수 통계를 조회한다. 지역 간 인프라 비교용. |
| `realty_policy_rules` | 단지에 종속되지 않는 **일반 규범**을 근거 조문·확인일과 함께 준다 — 취득세율표, |
| `realty_predict_price` | [유료] 단지의 **다음 달** 평균 매매가를 평형대별로 예측한다 (XGBoost v4_clean). |
| `realty_presale` | 아파트 청약(분양) 공고를 조회한다 — 분양가·청약 접수 일정·당첨자 발표일·입주 예정·위치. |
| `realty_presale_context` | 이 분양 공고를 **같은 시군구·평형 공고들과 견줘** 읽는다 — 공고 원문에만 있는 5축(대지비 비중·발코니확장 절대금액·중도금 무이자·층 프리미엄·㎡당 분양가)과 분포에서의 위치. 셀 표본 3건 미만이면 분위를 내지 않는다. |
| `realty_presale_cost` | 공고 원문(팩트시트) 기반 **결정론 계산**: 층별 분양가 + 발코니 확장비 + 회차별 |
| `realty_presale_funding_plan` | 공고 하나에 대해 **"내 자기자금으로 닫히는가"**를 결정론으로 판정한다 — 시점별 |
| `realty_presale_price_trend` | 같은 지역 분양 공고들의 **연도별 평당 분양가 추이**를 낸다 — "지금 넣을까, |
| `realty_presale_vs_market` | 청약(분양) 공고의 분양가가 주변 실거래 시세 대비 싼지/비싼지를 주택형별로 계산한다. |
| `realty_reconstruction` | [유료] 건령·거래활성 기반 재건축 **후보 스크리닝** 상위 단지를 조회한다. |
| `realty_redevelopment` | [유료] 서울시 정비사업(재개발·재건축·가로주택 등) 사업장 목록 — 사업명·유형· |
| `realty_redevelopment_burden` | 재개발·재건축 조합원의 권리가액과 추가 분담금(또는 환급금)을 결정론으로 계산한다 — |
| `realty_region_price_stats` | 지역의 아파트 실거래 시세 **추이**(월별)를 조회한다. 경매가가 싼지 판단하는 기준선이 된다. |
| `realty_region_rankings` | 지역(시군구) 순위를 조회한다 — "제일 비싼 동네 어디야?", "요즘 많이 오른 지역은?", |
| `realty_region_trend_basket` | 지역 가격 추이를 **양쪽 창에 모두 거래가 있는 동일 단지들로만** 계산한다. |
| `realty_remodel_feasibility` | **"이 아파트를 내가 원하는 대로 고칠 수 있나"**에 답하는 자리 — 두 축이다: **①벽**(내력벽을 헐어 방을 틀 수 있나) **②배관**(층상/층하 — 욕실·주방을 옮길 수 있나). |
| `realty_rental_yield` | [유료] 시군구별 월세 수익률·평균 매매가·평균 월세를 조회한다. 수익형 투자 스크리닝용. |
| `realty_onbid_sale_rate` | 공매(온비드)가 보통 감정가의 몇 %에 낙찰되는지와 개찰 결과 분포를 낸다 — 재산구분별로 갈라 읽어야 한다. |
| `realty_search_auctions` | 법원경매 물건을 지역·종류·감정가·유찰횟수로 필터링해 조회한다. |
| `realty_search_onbid` | 공매(온비드·캠코) 물건을 지역·용도·재산구분·감정가로 조회한다. 회차별 최저입찰가 일정을 함께 낸다. |
| `realty_search_complexes` | 아파트 단지를 이름·지역으로 검색하고 **평형별 실거래 시세**를 함께 돌려준다. |
| `realty_small_deposit_check` | 소액임차인 최우선변제의 **금액표를 고르는 도구**다 — 판정기가 아니다. |
| `realty_subscription_odds` | 청약 경쟁률과 **실제 당첨 가점 커트라인**을 낸다 — "나 가점 52점인데 당첨될까?"의 정량 근거. |
| `realty_subscription_score` | 민영주택 일반공급 가점제 점수(만점 84)를 **선언된 값**에 배점표를 적용해 계산한다 — |
| `realty_supply_demand_balance` | 시군구마다 앞으로 들어올 아파트와 늘어나는 세대를 같은 창으로 나눠 수급을 판정한다 — 입주(하한)·인허가(합산 금지)·세대 증가·순이동·거래량·경쟁률·낙찰가율·미분양을 한 행에. |
| `realty_supply_pipeline` | **아직 분양 공고가 안 난** 예정 공급을 사업계획승인 기준으로 본다 — "지금 넣을까, |
| `report_issue` | 답이 틀렸을 때 신고하거나(kind='결함'), 남길 값이 있는 **질문 원문을 기록한다**(kind='질문기록'). |
| `search` | 법원경매 물건을 자연어로 검색한다. **경매 전용** — 청약·분양 공고는 realty_presale, |

**"경매"는 두 제도이고 둘 다 담고 있습니다 — 갈라서 답합니다.** 법원경매(민사집행법·각급 법원·
사건번호 `2025타경1234`)와 공매(국세징수법·국유재산법 등·캠코 온비드·물건관리번호
`2026-0600-031235`)는 근거법·주관기관·권리 인수 규칙이 다릅니다. 두 원장을 합쳐 세거나
낙찰가율을 섞어 평균내지 않습니다.

공매 원장의 경계도 응답에 함께 싣습니다: **부동산만**(자동차·동산 없음) · **낙찰 결과는
최근 3개월분만**(온비드 전체 688,264건 중 113,673건) · **압류재산 주소는 원천에서 번지가
가려져 시군구까지만 유효** · **한 행이 물건이 아니라 공매조건(회차)**이라 물건 단위로 접어
돌려줍니다(물건 25,669개 ↔ 조건 90,018행) · **최저입찰가 '비공개'는 0이 아니라 null**.
공고 원문·감정평가서·권리분석은 담고 있지 않습니다.

## 이 서버가 스스로 지키는 것

데이터 서버의 값어치는 도구 개수가 아니라 **모델에게 거짓말하지 않는 것**이라고 봅니다.
그래서 응답에 다음을 싣습니다 — 코드로 확인하실 수 있습니다.

- **못 봄 ≠ 없음**: 빈 결과에 "왜 비었는지"를 붙입니다(미공표 vs 우리 수집 미도달을 구분).
- **조용한 절단 금지**: 상한에서 잘리면 `truncated`·`returned`·`total_matched`를 함께 냅니다.
  총계를 모르면 `null`이고, 반환 개수로 대신 채우지 않습니다(`honesty.py`).
- **미적용 인자 공시**: 선언했는데 안 먹은 필터는 `unapplied_conditions`로 올립니다.
- **폴백 은폐 금지**: 백엔드가 조용히 다른 값을 주면 그 사실을 응답에 적습니다.

## 한계 — 아는 것만 적습니다

- 데이터 신선도는 축마다 다릅니다(경매 1시간, 실거래 일간, 청약 경쟁률 주 1회). `/mcp/health`에
  실측값이 나옵니다.
- 권리분석(대항력·배당순위·인수 여부)은 **하지 않습니다.** 매각물건명세서 요약을 전달만 합니다.
- 이 저장소에는 우리 평가셋과 법령 큐레이션 원장이 없습니다(각각 우리가 유지하는 자산입니다).
  `policy_rules.sample.json`은 응답 모양을 보이기 위한 1토픽 샘플입니다.
- 크론·감시(pulse) 배선은 우리 운영 환경에 있고 이 저장소에 없습니다. 자기 백엔드로 돌린다면
  신선도 감시는 직접 붙여야 합니다.

## 문의·신고

도구 응답이 틀렸다고 판단되면 서버의 `report_issue` 도구로 보내 주십시오 — 그게 우리 평가셋에
회귀로 박히는 경로입니다. 라이선스는 `LICENSE`.