집생활 내비 (ZipLife Navi)

청년·신혼부부·전월세 세입자를 위한 AI 주거·이사 비서 MCP 서버

문제 정의

전월세로 이사하는 사람은 짧은 기간 안에 여러 가지를 동시에 처리해야 합니다.

• 내가 받을 수 있는 주거지원/대출/보증 제도가 뭔지 모른다

• 전입신고, 확정일자, 공과금 이전 같은 행정 일정을 놓친다

• 계약·입주·퇴거 시점마다 뭘 확인해야 하는지 매번 검색해야 한다

• 집주인/부동산에 연락할 때 어떻게 말을 꺼내야 할지 막막하다

집생활 내비는 사용자가 자연어로 자신의 상황("나 27살이고 서울에서 월세로 이사해")을 말하면, ① 상황 정리 → ② 혜택 후보 안내 → ③ 이사 타임라인 → ④ 계약 단계별 체크리스트 → ⑤ 연락 문장까지 한 번에 정리해주는 AI 주거생활 비서입니다.

Related MCP server: Korea Real Estate MCP

타깃 사용자

• 첫 자취/독립을 준비하는 청년 (월세, 전세)

• 신혼부부 (전세자금대출, 신혼희망타운 등 확인 필요)

• 이사를 앞두고 있거나 퇴거를 준비 중인 전월세 세입자

대표 사용 시나리오

시나리오 1. 월세 이사 예정 청년

"나 27살이고 서울에서 월세 70만원짜리 집으로 7월 20일에 이사해. 보증금은 1000만원이야. 받을 수 있는 지원 있어?"

parse_housing_profile → match_housing_benefits → generate_moving_timeline → 필요 시 generate_message_template 순으로 호출되어, 후보 제도 + 이사 D-day 체크리스트 + 집주인에게 보낼 문장까지 한 번에 안내됩니다.

시나리오 2. 신혼부부

"결혼 예정이고 전세집 알아보는 중이야. 보증금 1억 5천만원 정도 생각하는데 연봉은 4500이야."

parse_housing_profile이 혼인 상태·보증금·연봉을 추출하고, match_housing_benefits가 신혼부부 전세자금대출, 신혼희망타운 등을 후보로 안내하며 부족한 정보는 ask_missing_info로 되묻습니다.

시나리오 3. 퇴거 예정 세입자

"다음 달에 이사 나가는데 보증금 잘 돌려받으려면 뭐 해야 해?"

check_contract_tasks(stage="보증금반환")로 체크리스트를 안내하고, generate_message_template(purpose="보증금반환")으로 집주인에게 보낼 문장을 바로 만들어줍니다.

툴 목록 (9개)

모든 툴은 readOnlyHint: true로 부작용이 없으며, 서버는 stateless로 동작합니다(입력값을 저장하지 않음).

LH 임대주택단지 조회 (한국토지주택공사) — 검증 완료 ✅

search_lh_rental_complexes는 공공데이터포털의 LH 임대주택단지 조회 API를 실시간 호출해, 전국 시/도별 공공임대주택 단지 목록(단지명, 공급유형, 총세대수, 전용면적, 임대보증금, 월임대료)을 가져옵니다. 공식 활용가이드 문서로 정확한 응답 구조를 확인해 반영했습니다.

• 요청 URL: https://apis.data.go.kr/B552555/lhLeaseInfo1/lhLeaseInfo1

• 인증: PUBLIC_DATA_API_KEY (다른 국토부 API들과 같은 키 재사용 가능)

• 응답 구조가 독특합니다: [{"dsSch":...}, {"resHeader":[{"SS_CODE":...}], "dsList":[...실제 단지들...]}] — 최상위가 2-요소 리스트이고, 그 안의 dsList가 실제 데이터입니다. SS_CODE가 "Y"가 아니면 에러로 처리합니다.

• ⚠️ 임대보증금/월임대료는 이미 '원' 단위입니다. 국토부 실거래가 API(만원 단위)와 헷갈리지 않도록 처리했습니다.

• 전국 지원, 정확한 지역코드 반영: 서울(11), 부산(26), 대구(27), 인천(28), 대전(30), 울산(31), 경기(41), 충북(43), 충남(44), 경북(47), 경남(48), 제주(50), 세종(36110, 5자리), 강원(51, 강원특별자치도), 전북(52, 전북특별자치도), 광주/전남(12, 전남광주통합특별시로 행정구역 통합)

• 공급유형 필터: supply_type_keyword가 국민임대(07)/공공임대(08)/영구임대(09)/행복주택(10)/장기전세(11)/매입임대(13)/전세임대(17) 중 정확히 일치하면 SPL_TP_CD로 API에 함께 전달합니다. 다만 실제 테스트 결과 이 API가 SPL_TP_CD 파라미터를 무시하는 것이 확인되어, 서버 필터를 신뢰하지 않고 응답을 받은 뒤 항상 이름으로 다시 필터링합니다.

• total_count(전체 건수)를 통해 페이지네이션 잘림 여부를 안내

• first_move_in_ym(최초입주년월)이 간혹 비정상적인 값으로 나올 수 있는데, 이는 LH 원본 데이터 자체의 이상값으로 확인되었습니다(파싱 문제 아님).

시세 비교 (국토교통부 전월세 실거래가 API — 4개 주택유형) — 검증 완료 ✅

check_market_rent는 공공데이터포털의 국토교통부 실거래가 API를 실시간 호출해, 자치구 최근 거래 평균 보증금/월세를 계산하고 사용자 입력값과 비교합니다. 실제 발급받은 키로 4개 API 모두 승인받았으며, 아파트/오피스텔은 호출 테스트까지 완료했습니다.

• 인증: 환경변수 PUBLIC_DATA_API_KEY (공공데이터포털에서 발급, 자동승인, 4개 API 모두 같은 키로 사용 가능)

• 응답 포맷은 XML이 기본이라, JSON 파싱을 먼저 시도하고 실패하면 XML을 자동 파싱하도록 구현

• 전세/월세 거래를 자동으로 분리해서 평균을 계산합니다 (한 데이터셋에 섞여 있어, 합쳐서 평균 내면 왜곡되기 때문 — 실제 테스트에서 발견하고 수정한 부분)

• 유형별로 응답 필드명이 다른 것도 흡수해서 처리: 건물명(aptNm/offiNm/mhouseNm), 면적(excluUseAr/totalFloorAr) 등. 단독/다가구는 건물명·층 정보 자체가 없음(공식 API 스펙상 그러함)

• 일상 용어를 자동으로 인식: property_type에 "빌라", "다가구", "원룸", "투룸", "자취방" 같은 말을 그대로 넣어도 실제 API 유형으로 자동 매핑됩니다. "원룸"처럼 건물 유형이 특정되지 않는 표현은 오피스텔/연립다세대/단독다가구 세 유형을 모두 조회해 합쳐서 보여주고, 유형별로 몇 건씩 나왔는지(type_breakdown)도 함께 제공합니다.

• 고시원/셰어하우스 등 확정일자 신고 대상이 아닌 용어는 조회 불가 안내로 응답, 인식 불가능한 용어는 임의로 추정하지 않고 다시 물어보도록 안내

• 페이지네이션 잘림 감지: 한 번에 최대 200건만 가져오는데(numOfRows=200), 실제 거래량이 그보다 많은 경우(예: 강남/서초처럼 거래량 많은 지역) truncated_types에 "실제 전체 건수 대비 몇 건만 반영됐는지"를 표시해 평균이 부분 데이터 기준일 수 있음을 투명하게 알립니다.

• 전체 데이터 수집 옵션(fetch_all): 기본은 빠른 200건 조회. 잘린 경우 next_actions에 "사용자에게 먼저 시간이 더 걸릴 수 있음을 안내하고, 원하면 fetch_all=true로 다시 호출하라"는 안내가 담겨 있습니다. fetch_all=true로 호출하면 페이지네이션으로 전체 거래를 끝까지 가져옵니다(유형당 최대 2,000건 안전 상한, 무한 호출 방지).

• 현재 서울 25개 자치구만 지원 (법정동코드 매핑 필요, 타 지역은 확장 예정)

• 고시원/셰어하우스 등 확정일자 신고 대상이 아닌 주거 형태는 이 API들로 조회 불가능 (공식 통계 자체가 없음)

• 키가 없거나 미지원 지역/빈 결과면 명확한 안내 메시지로 응답 (에러로 죽지 않음)

• property_type은 기본값이 없는 필수 파라미터입니다 — 임의로 "아파트"를 가정하지 않도록, 반드시 사용자의 실제 표현(빌라/원룸 등 포함)을 받아 호출해야 합니다.

export PUBLIC_DATA_API_KEY="발급받은_인증키"  # Decoding 키 사용 (Encoding 키 아님)

실시간 정부 API 연동 (온통청년 청년정책API) — 검증 완료 ✅

search_official_youth_policy는 한국고용정보원이 운영하는 온통청년 청년정책 오픈API를 실시간으로 호출합니다. 실제 발급받은 키로 호출 테스트를 완료했고, 정상적으로 실시간 정책 데이터를 받아옵니다.

• 요청 URL: https://www.youthcenter.go.kr/go/ythip/getPlcy

• 인증: 환경변수 YOUTHCENTER_API_KEY에 발급받은 인증키를 설정 (마이페이지 > OPEN API에서 발급, 무료)

• 응답: rtnType=json으로 요청해 JSON으로 받음

• 키가 없거나 호출이 실패하면 자동으로 정적 BENEFITS 데이터로 폴백하여 서비스가 끊기지 않습니다.

• 응답 후처리: 빈 문자열/공백 정리, 신청기간을 2026-04-01 ~ 2026-04-14 형식으로 변환 + 현재 접수 상태(접수 중 / 접수 마감 / 접수 예정) 자동 계산, 이름+주관기관+신청기간이 동일한 재공고성 중복 항목 자동 제거

export YOUTHCENTER_API_KEY="발급받은_인증키"
python server.py

실제 응답 예시 ({"keyword": "주거"}로 호출):

{
  "summary": "온통청년 API에서 '주거' 관련 정책 N건을 실시간으로 확인했습니다.",
  "source": "youthcenter_live_api",
  "policies": [
    {
      "name": "부산 청년 월세 지원",
      "category": "전월세 및 주거급여 지원",
      "support_content": "월 최대 20만원, 최대 24개월 지원",
      "agency": "부산광역시 청년산학국 청년정책과",
      "apply_start": "2026-03-30", "apply_end": "2026-05-29",
      "apply_status": "접수 마감",
      "apply_url": "https://young.busan.go.kr/index.nm?menuCd=37",
      "age_min": "19", "age_max": "34",
      "income_min_manwon": "0", "income_max_manwon": "0",
      "additional_conditions": "부모님과 별도 거주 무주택청년 / 재산기준: 원가구 4억7천만원 이하..."
    }
  ]
}

marital_status_code_raw, income_condition_code_raw는 온통청년 자체 내부 코드값이며, 공식 코드정의서(엑셀)를 확보하지 못해 임의로 해석하지 않고 원본 그대로 전달합니다. 실제 소득/연령 조건은 income_min_manwon/income_max_manwon, age_min/age_max, additional_conditions 필드로 충분히 판단 가능합니다.

이 API는 "청년" 카테고리 정책만 다룹니다. 신혼부부 전세자금대출, 전세보증금 반환보증(청년 외), 주거급여 등은 소관 기관(주택도시기금, HUG, 복지로)이 달라 현재는 정적 데이터 + 공식 링크로 안내합니다. 추후 확장 가능한 부분입니다.

메시지 템플릿 (13가지 상황 × 3가지 톤)

보증금반환 · 하자확인 · 확정일자 · 이사일정 · 수리요청 · 계약연장문의 · 계약해지통보 · 월세감액요청 · 관리비문의 · 반려동물문의 · 소음문의 · 대출서류협조요청 · 공과금이전문의

각 상황마다 정중하게 / 단호하게 / 캐주얼하게 3가지 톤을 제공하며, 상황별 기본 수신자(집주인/관리사무소/통신사·도시가스 고객센터)가 자동 지정됩니다. [날짜], [사유]처럼 대괄호로 표시된 부분은 실제 내용으로 채워 넣어야 한다는 안내가 next_actions에 함께 나옵니다.

check_contract_tasks는 계약전/입주/갱신/퇴거/보증금반환 5단계를 지원합니다. 갱신 단계는 계약갱신청구권, 5% 증액 상한, 묵시적 갱신 여부, 임대인 변경 시 계약 승계 등 실무적으로 자주 놓치는 항목을 담고 있습니다.

ask_missing_info는 region은 있는데 district가 없으면 "정확히 몇 구(군)야?"를 자동으로 물어봅니다(시세 비교/LH 조회에 구 단위 정보가 필요하기 때문).

parse_housing_profile은 서울이 아닌 지역이 감지되면 "시세 비교(check_market_rent)는 현재 서울만 지원한다"는 안내를 caution에 자동으로 붙입니다 — 지역별 지원 범위가 툴마다 달라(시세 비교는 서울만, LH 조회는 전국) 생기는 혼선을 줄이기 위함입니다.

정책 데이터 (10개, 후보 안내용)

청년 월세지원 · 청년 전월세 보증금 대출 · 중소기업취업청년 전월세보증금대출 · 버팀목 전세자금대출 · 신혼부부 전세자금대출 · 신혼희망타운/공공임대 확인 · 서울 청년 이사비/중개보수 지원 · 지자체 주거비 지원 · 전세보증금 반환보증 · 주거급여

각 제도는 나이/지역/주거형태/혼인여부 등 명백히 어긋나는 조건만 걸러내고, 소득·자산 기준처럼 매년 바뀌는 항목은 "추가 확인 필요"로 안내하며 official_check(무엇을 확인해야 하는지)와 official_links(어디서 확인해야 하는지, 실제 클릭 가능한 공식 도메인)를 함께 제공합니다.

이 링크들은 개별 정책의 세부 조건 페이지가 아니라, 각 소관 기관의 안정적인 상위 포털입니다. 개별 공고/조건은 자주 바뀌어도 포털 도메인 자체는 잘 바뀌지 않기 때문에, 시간이 지나도 안내가 깨지지 않도록 이 방식을 택했습니다. (지자체별 세부 공고는 포털 내 검색 또는 관할 시/군/구청 홈페이지에서 확인이 필요합니다.)

로컬 실행 방법

pip install "mcp[cli]"
python server.py

기본적으로 Streamable HTTP transport로 실행되며, MCP Inspector로 접속해 각 툴을 테스트할 수 있습니다.

npx @modelcontextprotocol/inspector

예시 입력/출력

입력 (parse_housing_profile):

나 27살이고 서울 관악구에서 월세 70만원짜리 집으로 다음 달 20일에 이사해. 보증금은 천만원이야. 아직 계약 전이야.

출력 (요약):

{
  "summary": "다음과 같이 확인됩니다: 서울 관악구, 27세, 월세 거주 예정, 2026-08-20 이사 예정",
  "detected_profile": {
    "age": 27, "region": "서울", "district": "관악구",
    "housing_type": "월세", "move_date": "2026-08-20",
    "deposit": 10000000, "monthly_rent": 700000,
    "contract_status": "before_signing",
    "missing_fields": ["income", "marital_status", "is_homeless"]
  },
  "next_actions": ["ask_missing_info로 부족한 정보를 질문 형태로 정리해보세요.", "match_housing_benefits로 혜택 후보를 확인해보세요."]
}

match_housing_benefits 출력 (일부):

{
  "summary": "2개 제도가 후보로 확인되었습니다.",
  "matches": [
    {
      "name": "청년 월세지원",
      "status": "추가 확인 필요",
      "why_matched": "청년이면서 월세로 거주 중이거나 거주 예정이라 매칭되었습니다.",
      "missing_info": ["소득(월 기준 추정치)", "무주택 여부"],
      "official_check": ["거주지 지자체 청년월세지원 공고문", "해당 연도 소득/재산 기준표"],
      "caution": "지자체별로 명칭·지원금액·나이 기준이 다릅니다. 반드시 관할 지자체 공고로 재확인하세요."
    }
  ]
}

주의사항

• 법률/재정 자문이 아닙니다. 모든 혜택 매칭 결과는 후보 안내이며, 최종 신청 가능 여부는 반드시 공식 공고와 상담을 통해 확인해야 합니다.

• 개인정보를 저장하지 않습니다. 서버는 stateless로 동작하며, 입력값은 그 요청 처리 후 유지되지 않습니다.

• 최신 기준을 단정하지 않습니다. 소득·자산 기준처럼 매년 바뀌는 항목은 "확인 필요"로만 안내하고, 확인 가능한 공식 출처를 함께 제공합니다.