Korea Real Estate

korea-realestate-mcp

국토교통부 실거래가 공개자료로 아파트·빌라·오피스텔의 시세와 전세가율을 계산하는 MCP 서버, CLI, TypeScript 라이브러리입니다. Claude에게 "이 단지 84㎡ 시세가 어때?", "이 빌라 전세 4억이면 시세 대비 몇 %야?"라고 물으면 실거래 원자료로 근거 있는 숫자를 답할 수 있게 합니다.

English summary

> 세종 종촌동 가재마을4단지 75㎡ 전세 3억이면 어느 정도야?

## 세종특별자치시 종촌동 아파트 전세가율
단지: 가재마을4단지(센트레빌) (종촌동 640)
| 항목 | 값 |
|---|---|
| 전세가율 | 53.7% |
| ㎡당 매매 중앙값 (사분위) | 559만원 (538만원 ~ 567만원) |
| ㎡당 전세 중앙값 (사분위) | 300만원 (293만원 ~ 307만원) |
| 표본 | 매매 38건, 전세 36건 |
| 신뢰도 | 높음 |
| 입력 보증금 | 3억원 |
| 추정 전세가 (같은 면적) | 2억 2,506만원 |
| 보증금 ÷ 추정 전세가 | 133.3% |
| 비교 전세 중 위치 | ㎡당 보증금이 입력값 이하인 계약 100% |
| 추정 매매가 (같은 면적) | 4억 1,936만원 |
| 보증금 ÷ 추정 매매가 | 71.5% |
기준: 계약일 기준 최근 12개월 (2025-11-11 초과 ~ 2026-11-11) / 전용면적 75㎡ ±3% / 해제 거래 제외 (1건) / 직거래 제외 (3건) / …
제외: 해제 1건, 직거래 3건 (매매) / 월세 42건, 갱신 23건 (전세 표본에서)
참고 자료이며 계약·투자 판단의 근거가 아닙니다.
출처: 국토교통부 실거래가 공개자료(공공데이터포털), 조회 2026-11-11 23:12 KST

무엇이 다른가

• 13종 전부: 아파트·연립다세대·단독다가구·오피스텔의 매매와 전월세, 분양·입주권, 상업업무용, 토지, 공장·창고.
• 빠짐없이 받기: 모든 쪽을 받고, 받은 건수가 totalCount보다 적으면 다시 받거나 실패로 알립니다. 한 쪽만 받고 끝내지 않습니다.
• 조용한 0건을 막기: 이 API는 잘못된 지역 코드·미래 달·옛 행정구역 코드에도 오류 없이 0건을 돌려줍니다. 호출 전에 코드표와 날짜로 먼저 검증합니다.
• 2026-07 행정구역 개편 반영: "인천 중구", "광주광역시 북구", "화성시"를 새 코드(제물포구·영종구, 전남광주통합특별시 북구, 화성시 4개 구)로 바꿔 조회합니다. API가 과거 거래도 새 코드로만 돌려주는 것을 실측으로 확인했습니다.
• 오류를 할 일로 바꾸기: 403 코드 30은 "키가 틀림"과 "그 서비스 미신청"이 바이트까지 같은 응답입니다. 같은 키로 다른 서비스가 성공했으면 미신청으로 좁히고, 신청할 데이터셋 번호와 링크를 알려 줍니다. doctor 명령으로 13종의 신청 상태를 한 번에 봅니다.
• 분석 기준을 숨기지 않기: 해제·직거래 제외 건수, 면적 허용 오차, 신고 기한 때문에 덜 잡힌 최근 달, 표본 수와 신뢰도 기준을 결과에 함께 냅니다.
• 키를 새지 않게: 인증키는 URL 쿼리에 실려 가므로, URL과 원본 예외를 오류·로그·도구 결과 어디에도 내보내지 않습니다. 테스트로 확인합니다. 보안 설계

시작하기

1. 인증키 발급과 활용신청

1. 공공데이터포털에 가입하고 아래 데이터셋마다 활용신청을 합니다. 자동승인이며 반영까지 최대 1시간 걸릴 수 있습니다.
2. 마이페이지에서 일반 인증키를 복사합니다. Encoding·Decoding 어느 쪽이든 됩니다.

용도	데이터셋
아파트 시세·전세가율	아파트 매매, 아파트 전월세
빌라(연립·다세대)	매매, 전월세
오피스텔	매매, 전월세
그 밖 (조회만)	단독·다가구 매매·전월세, 분양·입주권, 상업업무용, 토지, 공장·창고, 아파트 매매 상세

신청 상태 확인:

DATA_GO_KR_SERVICE_KEY=발급받은키 npx -y [email protected] doctor

2. Claude에 연결

Claude Code

claude mcp add korea-realestate -e DATA_GO_KR_SERVICE_KEY=발급받은키 -- npx -y [email protected]

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "korea-realestate": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은키" }
    }
  }
}

설정 파일에 키가 평문으로 남습니다. 파일 권한을 확인하고, 키가 새면 포털에서 재발급하세요.

MCP 도구

도구	하는 일
resolve_region	지역 이름 → 시군구 코드·법정동. 이름이 겹치면 후보와 "region에 넣을 값"을 돌려줍니다
search_deals	13종 실거래 원자료를 최신순으로 (최대 50건, 24개월)
market_summary	매매 시세: 중앙값, 범위, 사분위, ㎡당·3.3㎡당 가격, 월별 추이, 최근 거래
jeonse_ratio	전세가율. 보증금과 면적을 주면 추정 전세가·매매가 대비 비율과 비교 전세 중 위치

모든 도구는 읽기 전용이고, 결과 끝에 출처와 조회 시각을 붙입니다.

지역은 이렇게 넣을 수 있습니다:

• 시군구: 강남구, 서울 강남구, 수원시 영통구, 세종
• 법정동: 마포구 아현동, 아현동, 세종 조치원읍
• 코드: 시군구 5자리, 법정동 10자리
• 행정동·줄임말·옛 이름: 역삼1동, 강남, 인천 중구

CLI

export DATA_GO_KR_SERVICE_KEY=발급받은키

korea-realestate-mcp doctor
korea-realestate-mcp region 신사동
korea-realestate-mcp deals   --type apt --deal rent --region "마포구 아현동" --months 3
korea-realestate-mcp summary --type apt --region "마포구 아현동" --name 래미안푸르지오 --area 84
korea-realestate-mcp ratio   --type rh --region "강서구 화곡동" --area 59 --deposit 4억 --json

인자 없이 터미널에서 실행하면 도움말이 나오고, 파이프로 실행하면(MCP 클라이언트가 띄울 때) stdio MCP 서버로 동작합니다.

라이브러리

import { createClient, summarize, resolveRegion } from "korea-realestate-mcp";

const client = createClient(); // DATA_GO_KR_SERVICE_KEY를 읽음. 또는 { serviceKey }
const deals = await client.fetchMonth("apt-sale", "11440", "202610"); // 금액은 원 단위
const r = await summarize({ client }, { propertyType: "apt", region: "마포구 아현동", area: 84 });

fetch, 캐시(CacheStore), 시계를 주입할 수 있습니다. 라이브러리 진입점은 MCP SDK를 불러오지 않습니다.

算出基準と制限事項

• 期間：「直近12か月」は、KSTの本日を基準とした契約日から12か月間です。APIは13か月分を呼び出します。
• 直近2か月：実取引の届出期限が30日のため、件数が少なくなります。月別推移では * を付けて示します。
• 除外：取消取引は常に除外し、当事者間取引はデフォルトで除外します（親族間取引などが相場を押し下げる可能性があります）。除外件数は常に表示します。
• チョンセのサンプル：月額賃料が0ウォンで、更新契約ではないものです。契約区分が空欄の契約は含めます（実測では多数あります）。
• 面積の許容誤差：団地を指定した場合は±3％、アパートの地域範囲は±10％、ヴィラ・オフィステルは±15％です。
• チョンセ価格比率のサンプル：売買・チョンセがそれぞれ5件以上の場合のみ算出します。信頼度が「高い」となるのは、団地を指定し、それぞれ10件以上あり、直近6か月にそれぞれ3件以上ある場合です。地域範囲の場合は最大でも「普通」です。
• 判断は行いません：数値と基準のみを返します。結果は公開された実取引に基づく参考資料であり、契約・投資判断の根拠にはなりません。契約前に登記簿と専門家による確認が必要です。
• 実測範囲：13種類すべてについて、実際の応答（世宗、2026-10）でフィールドを確認しました。サービスごとのデータ開始月は確認していません。
• 非公開の地番：一戸建て・多世帯住宅、土地、工場・倉庫の売買では、公開データ上、地番の一部が 2** のように伏せられています。一戸建て・多世帯住宅の賃貸では地番がありません。
• 呼び出し上限：1回の検索でAPIを呼び出せるのは80回までです。開発アカウントは1日10,000回です。複数の区を含む市全体（例：水原市の24か月分のチョンセ価格比率）は上限を超えるため、区を指定して範囲を絞ってください。

セキュリティ設計

• 認証キーは環境変数 DATA_GO_KR_SERVICE_KEY からのみ受け取ります。ツールの入力項目にキーはありません。
• EncodingキーとDecodingキーを同じ元の値に正規化してから、1回だけエンコードします。二重にエンコードすると403エラーになります。
• リクエストURLにキーが含まれるため、URL・元の例外（Failed to parse URL from … など）・レスポンス本文をエラーに含めません。すべての出力で、キーの元の値・エンコード形式・+→空白形式を伏せるマスキングを行います。
• リクエストは https://apis.data.go.kr にのみ送信し、redirect: "error"、タイムアウト15秒、レスポンス上限16MB、同時実行4件を設定します。
• XMLではDOCTYPEを拒否し、値は文字列のまま、200文字を上限として読み取ります。アップストリームのコード値は、数値の場合のみ信頼します。
• ログはstderrにのみ出力し、サービス・地域・月・状態だけを記録します。
• リポジトリではgitleaks（serviceKeyルールを含む）・Semgrep・zizmor・CodeQL・Dependabotを使用し、アクションはSHAで固定します。npmの公開はGitHub Actionsでprovenanceを付けて行い、初回公開後はtrusted publishing（OIDC）のみを使用します。

脆弱性はSECURITY.mdに記載された方法でお知らせください。

開発

pnpm install
pnpm test        # 단위·통합 테스트 (네트워크 없음)
pnpm typecheck && pnpm lint && pnpm build
LIVE=1 DATA_GO_KR_SERVICE_KEY=… pnpm vitest run test/live.test.ts   # 실제 API 스모크 (약 3건 호출)
pnpm gen:regions <법정동코드 전체자료.txt>                            # 지역 코드표 다시 만들기

設計ドキュメント：docs/superpowers/specs/2026-11-11-v0.1-design.md

データソースとライセンス

• 実取引価格：国土交通部の実取引価格公開API（公共データポータル）。このパッケージは実取引データを含まず、ユーザーのキーを使って直接呼び出します。
• 地域コード表（data/regions.json）：行政安全部の行政標準コード管理システムにある法定洞コードの全データ（公共ヌリ第1種、出典：行政安全部）。
• コード：MIT

---

English

korea-realestate-mcpは、韓国の公式不動産取引データ（MOLIT、data.go.kr経由）を扱うMCPサーバー、CLI、TypeScriptライブラリです。

• 13種類すべての取引データセット（アパート、連棟住宅、一戸建て住宅、オフィステル、分譲権、商業用不動産、土地、工業用不動産）を検索します。
• 市場の概要（中央値、IQR、㎡あたりの価格、月別推移）とチョンセ（一括保証金型賃貸）の比率を算出し、すべての除外項目としきい値を表示します。
• 韓国の地域名、法定洞コード、2026年以前の行政区域名を、APIが実際に受け付けるコードに変換します。誤ったコードや廃止されたコードに対してAPIはエラーなしで空の結果を返すため、呼び出し前に入力を検証します。
• 不透明なゲートウェイエラーを、登録すべきデータセットを含む実用的なメッセージに変換します。
• すべてのエラー、ログ、ツールの結果からAPIキーを除外します。キーはURLのクエリに含まれるため、URLや生の例外は表示しません。テストでこれを検証します。

DATA_GO_KR_SERVICE_KEY にdata.go.krの無料サービスキーが必要です。結果は参考データであり、助言ではありません。