korea realty

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

법원경매·국토교통부 실거래·청약 공고 원문·대출/세금 계산을 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

claude mcp add --transport http korea-realty https://realty.sallim.app/mcp

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

도구

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

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

전체 도구 목록 (47종)

디렉토리·크롤러가 읽는 자리다. 라이브 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_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_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_rental_yield	[유료] 시군구별 월세 수익률·평균 매매가·평균 월세를 조회한다. 수익형 투자 스크리닝용.
realty_search_auctions	법원경매 물건을 지역·종류·감정가·유찰횟수로 필터링해 조회한다.
realty_search_complexes	아파트 단지를 이름·지역으로 검색하고 평형별 실거래 시세를 함께 돌려준다.
realty_subscription_odds	청약 경쟁률과 실제 당첨 가점 커트라인을 낸다 — "나 가점 52점인데 당첨될까?"의 정량 근거.
realty_subscription_score	민영주택 일반공급 가점제 점수(만점 84)를 선언된 값에 배점표를 적용해 계산한다 —
realty_supply_pipeline	아직 분양 공고가 안 난 예정 공급을 사업계획승인 기준으로 본다 — "지금 넣을까,
report_issue	답이 틀렸을 때 신고하거나(kind='결함'), 남길 값이 있는 질문 원문을 기록한다(kind='질문기록').
search	법원경매 물건을 자연어로 검색한다. 경매 전용 — 청약·분양 공고는 realty_presale,

공매(온비드)는 없습니다. 이 서버의 "경매"는 법원경매(민사집행법)만입니다.

이 서버가 스스로 지키는 것

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

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

한계 — 아는 것만 적습니다

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

문의·신고

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