KRE-MCP · 한국 아파트 실거래가를 AI와 함께 조회하기

KRE-MCP는 AI가 국토교통부의 아파트 매매·전월세·분양권 전매 실거래가를 조회하고 분석하는 Python MCP 서버입니다.

Claude Desktop이나 MCP를 지원하는 개발 도구에서 질문하면, AI가 필요한 조회 도구를 호출하고 결과를 설명합니다. Python 개발자는 LangChain 에이전트에 연결해 공공데이터를 사용하는 AI 실습을 만들 수 있습니다.

PyPI 패키지 · 소스 저장소 · 공공데이터포털

이 프로젝트는 국토교통부 공개 API를 연결하는 독립 프로젝트입니다. 한국부동산원 R-ONE 통계 서비스나 정부기관의 공식 MCP 제품이 아닙니다. korea-realestate-mcp와도 별개의 패키지입니다.

목차

1. 이 패키지로 할 수 있는 일
2. 어떻게 동작하나요?
3. 시작 전 준비
4. 설치와 실행 확인
5. AI 클라이언트에 연결
6. 첫 조회와 단계별 실습
7. 도구 입력 명세
8. 조회 결과 읽는 법
9. Python과 LangChain에서 사용
10. 문제 해결
11. 자주 묻는 질문
12. 개발·검증·배포

이 패키지로 할 수 있는 일

1. 아파트 매매 실거래가 조회

realestate_search_apt_trade는 지정한 지역과 계약월의 아파트 매매 신고 내역을 가져옵니다. 아파트 이름, 계약일, 거래금액, 전용면적, 층 등 API가 제공하는 필드를 확인할 수 있습니다.

질문 예시

지역코드 11680의 2026년 1월 아파트 매매 거래를 10건 조회하고, 단지명·계약일·금액·전용면적·층을 표로 보여줘.

2. 아파트 분양권·입주권 전매 실거래가 조회

realestate_search_presale_trade는 같은 방식으로 분양권·입주권 전매 신고 내역을 가져옵니다. 거래금액·면적과 함께 권리 구분(ownershipGbn), 취소 관련 필드를 확인할 수 있습니다.

질문 예시

같은 지역과 월의 분양권 전매도 10건 조회해줘. 매매 결과와 구분해서 보여주고, 권리 구분 필드가 있으면 함께 설명해줘.

3. 페이지를 이어서 조회하고 원본 필드 확인

한 번에 최대 100건을 조회하며, 전체 건수와 다음 페이지 여부를 반환합니다. AI 클라이언트나 Python 코드에서 page를 늘려 다음 데이터를 가져올 수 있습니다. 서버가 단지명이나 숫자를 임의로 바꾸지 않으므로 원본 필드를 기준으로 데이터 처리 수업을 진행하기에도 적합합니다.

4. 지역명 검색부터 분석까지

지원 범위와 분석 기준

• 원본 조회 3개 도구는 한 페이지를 반환하며 취소 거래도 그대로 포함합니다.
• 분석 도구는 필요한 월의 전체 페이지를 수집하고, 취소 관련 표시가 있는 거래를 제외한 뒤 집계합니다. 수집 건수가 API 전체 건수와 다르면 오류를 반환합니다.
• 단지명 필터는 공백을 무시한 정확한 이름 일치입니다. “래미안”처럼 이름 일부만 입력하는 검색은 지원하지 않습니다. 먼저 원본 조회에서 단지명을 확인하세요.
• 추이·전세가율·단지 요약의 조회 기간은 1~12개월입니다. 월·지역·거래 종류당 최대 10,000건까지 수집하며, 한도 초과 시 부분 통계를 내지 않습니다. 기간이 길거나 전월세 거래가 많은 지역은 여러 API 호출이 필요합니다.
• 가격이 없거나 유효하지 않으면 가격 통계에서 제외합니다. 표본이 없으면 평균·변동률·전세가율은 null로 반환하며 0으로 대체하지 않습니다.
• 호가·매물 검색·시세 예측·한국부동산원 공식 가격지수·웹 대시보드는 제공하지 않습니다.

어떻게 동작하나요?

MCP(Model Context Protocol)는 AI 애플리케이션이 외부 도구를 호출할 때 사용하는 통신 규약입니다. KRE-MCP는 이 규약에 맞춰 8개 조회·분석 도구를 제공합니다.

사용자의 질문
    ↓
AI 클라이언트 / LangChain 에이전트
    ↓ 도구 이름과 조회 조건 전달
KRE-MCP 서버 (내 컴퓨터에서 실행)
    ↓ 인증키로 HTTPS 요청
국토교통부 공공데이터 API
    ↓ 실제 거래 데이터
KRE-MCP → AI 클라이언트 → 표·설명으로 답변

• 서버는 데이터를 조회합니다. 자체 LLM이나 대화 화면은 포함하지 않습니다.
• 클라이언트가 서버 프로세스를 실행하고 표준입출력(stdio)으로 통신합니다. 별도의 포트 설정은 필요하지 않습니다.
• 인증키는 서버의 PUBLIC_DATA_API_KEY 환경변수에 넣습니다. 질문이나 도구 입력에는 넣지 않습니다.
• 서버는 거래 데이터를 별도 데이터베이스에 저장하거나 캐시하지 않습니다. 반복 조회도 API 호출량을 사용합니다.

시작 전 준비

준비물

• 인터넷 연결이 가능한 macOS·Windows·Linux 환경
• uv 또는 Python 3.10 이상
• 로컬 stdio MCP 서버를 지원하는 클라이언트, 또는 Python 실행 환경
• 공공데이터포털 계정과 아래 3개 API 중 사용할 서비스의 활용승인

공공데이터포털 API 신청

1. 공공데이터포털에 로그인합니다.
2. 다음 API 각각에서 활용신청을 진행합니다.
3. 마이페이지의 활용신청 내역에서 승인 상태를 확인합니다.
4. **일반 인증키(Decoding)**를 준비합니다.

모든 기능을 사용하려면 3개 API를 모두 신청하세요. 지역명 검색은 API 키 없이도 가능합니다. 한 API의 승인만으로 다른 API까지 사용할 수 있다고 가정하지 마세요. 동일한 인증키를 쓰더라도 서비스별 활용승인은 확인해야 합니다. 호출 한도와 승인 상태는 포털의 본인 계정에서 확인할 수 있습니다.

일반 인증키(Encoding)도 서버에서 한 번 디코딩하여 처리하지만, 처음 설정할 때는 Decoding 키를 권장합니다. 수강생마다 본인의 키를 사용하세요.

설치와 실행 확인

방법 A. uvx로 실행 — 교육 실습 권장

uvx는 패키지와 의존성을 격리된 환경에 준비해 실행하는 명령입니다. 저장소를 내려받거나 먼저 pip install kre-mcp를 실행할 필요가 없습니다.

uv가 없다면 설치

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell:

winget install --id=astral-sh.uv -e

설치 후 터미널을 다시 열고 확인합니다. 다른 설치 방법은 uv 공식 설치 안내를 참고하세요.

uv --version
uvx --from kre-mcp==0.2.0 kre-mcp --version

두 번째 명령에서 0.2.0이 출력되면 패키지 설치와 실행 진입점이 정상입니다. 이 명령만으로 인증키나 API 활용승인까지 검증되지는 않습니다.

방법 B. pip로 가상환경에 설치

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install kre-mcp==0.2.0
kre-mcp --version

Windows PowerShell에서는 가상환경을 활성화하지 않고 실행할 수도 있습니다.

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install kre-mcp==0.2.0
.\.venv\Scripts\kre-mcp.exe --version

MCP 클라이언트가 이 가상환경을 자동으로 사용하지는 않습니다. pip 방식으로 설치했다면 서버 설정의 command에 해당 환경의 kre-mcp 실행 파일 절대 경로를 지정하고 args는 빈 배열로 설정하세요.

인증키를 셸에 설정할 때

Python 실습이나 직접 실행할 때 사용합니다. 아래 문자열을 본인 키로 교체하세요.

macOS / Linux:

export PUBLIC_DATA_API_KEY='본인의 공공데이터포털 인증키'

Windows PowerShell:

$env:PUBLIC_DATA_API_KEY = '본인의 공공데이터포털 인증키'

이 설정은 해당 터미널과 그 터미널에서 시작한 프로세스에 적용됩니다. 바탕화면에서 실행한 GUI 앱에는 전달되지 않을 수 있으므로, 다음 클라이언트 설정의 env를 사용하는 편이 명확합니다.

.env 파일은 자동으로 읽지 않습니다. 파일에 키를 적는 것만으로 서버에 설정되지 않습니다.

AI 클라이언트에 연결

Claude Desktop

1. Claude Desktop의 Settings → Developer → Edit Config에서 설정 파일을 엽니다.
2. 아래 kre-mcp 항목을 mcpServers 안에 추가합니다. 기존 서버 설정이 있다면 유지하세요.
3. 인증키 문자열을 교체하고 저장합니다.
4. 앱을 완전히 종료한 뒤 다시 실행합니다.
5. 사용 가능한 도구 목록에 8개 도구가 나타나는지 확인합니다.

{
  "mcpServers": {
    "kre-mcp": {
      "command": "uvx",
      "args": ["--from", "kre-mcp==0.2.0", "kre-mcp"],
      "env": {
        "PUBLIC_DATA_API_KEY": "본인의 공공데이터포털 인증키"
      }
    }
  }
}

JSON에는 주석이나 마지막 항목 뒤 쉼표를 넣지 마세요. Windows 경로를 직접 입력할 때는 C:\\Users\\이름\\...\\uvx.exe처럼 역슬래시를 두 번 적습니다.

설정 파일 위치와 연결 과정은 MCP 공식 로컬 서버 연결 안내를 참고하세요. 클라이언트 버전에 따라 메뉴 위치는 달라질 수 있습니다.

VS Code

작업 폴더의 .vscode/mcp.json에는 아래 형식을 사용합니다. Claude Desktop의 mcpServers와 달리 최상위 키가 servers입니다. 암호 입력 항목으로 키를 받아 설정 파일에 직접 적지 않는 예제입니다.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "public-data-api-key",
      "description": "공공데이터포털 일반 인증키",
      "password": true
    }
  ],
  "servers": {
    "kre-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "kre-mcp==0.2.0", "kre-mcp"],
      "env": {
        "PUBLIC_DATA_API_KEY": "${input:public-data-api-key}"
      }
    }
  }
}

서버 시작·도구 활성화는 VS Code MCP 안내를 따르세요. 그 밖의 클라이언트도 command, args, env를 이용한 로컬 stdio 연결이 가능하면 같은 서버를 사용할 수 있습니다. 설정 파일 형식은 각 클라이언트에 맞춰야 합니다.

연결 성공 확인

위 제공 도구 표의 8개 도구가 보이면 도구 탐색 단계가 성공한 것입니다. 먼저 인증키 없이 realestate_get_region_code에 query="서울 강남구"를 입력해 연결을 확인할 수도 있습니다.

이어서 실제 조회를 한 번 실행해야 키·API 승인·네트워크까지 확인할 수 있습니다. uvx kre-mcp를 터미널에서 직접 실행했을 때 화면이 조용한 것은 정상입니다. 서버는 MCP 클라이언트의 요청을 기다립니다. 직접 실행한 프로세스를 끝내려면 Ctrl+C를 누르세요.

첫 조회와 단계별 실습

실습 1. 조건이 분명한 첫 질문

지역코드 11680, 계약년월 202601로 아파트 매매 실거래가 첫 페이지를 5건 조회해줘. 전체 건수와 이번에 받은 건수를 따로 알려줘.

확인할 점: 도구 호출의 입력이 region_code="11680", deal_ym="202601", page=1, page_size=5인지, 응답에 total_count와 returned_count가 있는지 확인합니다.

실습 2. 결과를 읽기 쉬운 표로 정리

방금 받은 거래에서 단지명, 계약일, 전용면적, 층, 거래금액을 표로 만들어줘. 금액 단위는 만원으로 표시하고, 빈 필드는 정보 없음으로 적어줘.

확인할 점: dealAmount를 원으로 오해하지 않았는지, 빈 값을 임의로 채우지 않았는지 확인합니다. 예를 들어 120,000만원은 12억원입니다.

실습 3. 분양권 전매와 구분

같은 지역과 월의 분양권 전매를 첫 페이지 5건 조회해줘. 앞서 본 아파트 매매와 별개의 목록으로 보여줘.

확인할 점: realestate_search_presale_trade가 호출되는지, trade_type이 presale인지 확인합니다. 일반 매매와 분양권 전매를 같은 거래 목록으로 합치지 않습니다.

실습 4. 페이지네이션

매매 결과의 has_next가 true라면 같은 page_size로 2페이지를 조회해줘. 지금까지 전체 중 몇 건을 받았는지 구분해서 설명해줘.

확인할 점: page는 1부터 시작합니다. 이어서 조회할 때 page_size를 유지해야 겹치거나 건너뛰는 구간을 피할 수 있습니다. 여러 페이지를 읽었다고 해서 전체를 읽은 것은 아닙니다.

실습 5. 데이터 해석 연습

지금 조회한 거래에서 취소 관련 필드를 확인해줘. 이 표만으로 해당 지역 전체의 평균 시세를 말할 수 있는지도 설명해줘.

확인할 점: 취소 거래를 서버가 자동 제외하지 않는다는 점, 월·지역·면적·단지별 거래 구성이 다르다는 점, 현재 결과가 전체 데이터인지 확인합니다.

실습 6. 지역명으로 조회 시작하기

지역코드 검색 도구로 “분당구”를 찾아줘. 후보의 전체 지역명을 확인한 다음 2026년 1월 전월세 거래 5건을 조회해줘.

확인할 점: “중구”처럼 동명이 많은 이름은 여러 후보가 나옵니다. requires_confirmation=true라면 시도·시군구를 확인한 뒤 선택합니다. 퍼지 점수는 문자열 유사도이지 정답 확률이 아닙니다.

실습 7. 서버가 계산한 월별 통계 사용하기

종로구의 2026년 1~3월 매매 추이를 분석 도구로 조회해줘. 월별 거래 건수·평균·중앙값·변동률과 취소 제외 건수를 함께 설명해줘.

확인할 점: coverage의 수집 건수, 제외 건수, 가격 통계의 count를 대조합니다. 직전 달 거래가 없으면 그다음 달 변동률도 null입니다. 거래 표본의 변화율을 공식 시세지수로 부르지 않습니다.

실습 8. 같은 조건으로 지역 비교

종로구와 중구의 2026년 1월 아파트 매매를 80~85㎡ 조건으로 비교해줘. 평균·중앙값·㎡당 금액과 각 지역의 표본 수를 알려줘.

확인할 점: realestate_compare_regions는 서로 다른 지역 2~5개와 같은 계약월을 받습니다. 면적 조건을 맞춰도 건축연도·층·단지 구성은 다를 수 있습니다.

실습 9. 전세가율과 단지 요약

종로구의 2026년 1월 전세가율을 계산해줘. 매매와 전세가 모두 있는 그룹 하나를 고르고, 같은 단지명·법정동·지번으로 종합 요약도 조회해줘.

확인할 점: 월세를 전세로 포함하지 않았는지, 매매·전세 표본 수가 몇 건인지 확인합니다. 동명 단지가 있으면 요약 도구가 status="ambiguous"와 주소 후보를 반환하므로 조건을 구체화합니다.

강사용 진행 예시 (약 30분)

API 활용신청은 수업 전에 끝내는 것을 권장합니다. 실습에서는 버전을 고정하고 5~10건부터 조회하면 결과를 비교하기 쉽습니다.

도구 입력 명세

원본 조회 도구 3개

realestate_search_apt_trade, realestate_search_apt_rent, realestate_search_presale_trade는 같은 입력 구조를 사용합니다.

도구 호출 입력 예제

{
  "region_code": "11680",
  "deal_ym": "202601",
  "page": 1,
  "page_size": 5
}

• 서울 종로구 예시는 11110, 서울 강남구 예시는 11680입니다. 다른 지역은 행정표준코드관리시스템에서 법정동 코드를 확인하고 앞 5자리를 사용하세요.
• "강남구", "1168010100", "2026-01"은 이 도구가 받는 입력 형식이 아닙니다.
• 계약년월은 조회하는 날짜가 아니라 계약이 이루어진 월입니다.
• 지역코드는 5자리 형식을 검사하지만 실제 존재 여부를 별도 코드표로 검증하지 않습니다.
• 현재 월·신고 지연·거래가 없는 조건에서는 결과가 적거나 없을 수 있습니다. 특정 건수를 보장하지 않습니다.

지역명 → 코드: realestate_get_region_code

{"query": "서울 강남구", "limit": 5}

matches의 각 후보에는 region_code, region_name, matched_name, match_type, score가 있습니다. total_candidates는 전체 후보 수입니다. 정확·포함 일치가 없을 때만 유사도 0.65 이상 퍼지 후보를 반환합니다. 후보가 없으면 빈 배열입니다.

행정안전부 법정동코드 전체자료의 2026-10-08 스냅샷을 패키지에 포함합니다. 현행 법정동에서 실제 조회용 앞 5자리 지역 256개를 추출했습니다. 자동 갱신 서비스가 아니며, 과거 폐지 지역코드는 포함하지 않습니다. 행정구역 개편 전 과거 거래는 당시 코드를 별도로 확인해야 할 수 있습니다.

매매 추이: realestate_analyze_price_trend

{"region_code": "11110", "start_ym": "202601", "end_ym": "202603", "area_min": 80, "area_max": 85}

응답 months에는 각 월의 price_manwon, price_per_m2_manwon, change_pct, coverage가 있습니다. 가격 통계에는 count, mean, median, min, max가 포함됩니다. ㎡당 금액은 개별 거래의 금액/면적을 구한 뒤 집계합니다.

change_pct = (이번 달 평균 매매가 / 직전 달 평균 매매가 - 1) × 100입니다. 반올림 전 평균으로 계산하고 표시값은 소수 둘째 자리까지 반환합니다. 첫 달 또는 비교할 어느 한 달에 유효 가격이 없으면 null입니다.

지역 비교: realestate_compare_regions

region_codes에 서로 다른 코드 2~5개, deal_ym에 한 계약월을 입력합니다. area_min, area_max는 선택사항입니다. 응답 regions에 지역별 가격 통계와 수집·제외 내역이 있습니다.

{"region_codes": ["11110", "11140"], "deal_ym": "202601", "area_min": 80, "area_max": 85}

전세가율: realestate_analyze_rent_ratio

추이 도구와 동일하게 region_code, start_ym, end_ym이 필수이며 apt_name, area_min, area_max가 선택사항입니다. 매매와 전월세 API의 활용승인이 모두 필요합니다.

{"region_code": "11110", "start_ym": "202601", "end_ym": "202603"}

계산 규칙:

1. 취소 거래를 제외하고 전월세 중 monthlyRent=0, 보증금이 양수인 전세만 선택합니다.
2. 같은 조회 지역에서 단지명·법정동명·지번·정확한 전용면적이 같은 매매·전세 거래를 그룹으로 묶습니다. 식별 필드나 가격·면적이 없으면 제외합니다.
3. 그룹별 ratio_pct = 평균 전세보증금 / 평균 매매금액 × 100을 계산합니다.
4. mean_gap_manwon은 평균 매매금액 − 평균 전세보증금입니다. 취득 비용이나 권리관계 등을 반영한 투자 필요 자금이 아닙니다.

groups에는 그룹별 두 표본 수와 평균 금액, 비율이 있습니다. 같은 호수·같은 계약일을 매칭한 결과는 아닙니다. 매칭 그룹이 없으면 median_group_ratio_pct=null입니다. 이 중앙값은 모든 매칭 그룹의 비율을 같은 가중치로 집계합니다. 그룹 목록은 최대 100개를 표시하고 matched_group_count와 returned_group_count로 구분합니다. 다른 면적·주소의 거래를 자동으로 대체하지 않습니다.

단지 요약: realestate_get_apt_summary

{"region_code": "11110", "apt_name": "조회 결과에서 확인한 단지명", "start_ym": "202601", "end_ym": "202603"}

응답에는 sale(매매), rent(전세·월세 분리 통계), rent_ratio, area_groups(정확한 면적별 매매 통계), recent_sales(계약일 내림차순 최대 10건), coverage가 포함됩니다. 동명이 여러 주소에 존재하면 status="ambiguous"와 주소 후보를 반환합니다.

전월세 조회가 실패하면 매매 정보는 제공하되 complete=false, rent_status="unavailable", rent_error를 명시하고 임대차·전세가율 값은 null로 둡니다. 이것을 임대차 거래가 없다는 뜻으로 해석하면 안 됩니다. found=false도 조회한 기간·필터의 데이터가 없다는 뜻이지 단지가 존재하지 않는다는 뜻은 아닙니다.

조회 결과 읽는 법

다음은 형식 설명을 위한 가상 응답입니다. 실제 단지나 실제 거래 사례를 나타내지 않습니다. items의 필드는 일부만 표시했습니다.

{
  "source": "국토교통부 실거래가 공개자료 (공공데이터포털)",
  "trade_type": "apartment",
  "region_code": "11680",
  "deal_ym": "202601",
  "page": 1,
  "page_size": 1,
  "total_count": 12,
  "items": [
    {
      "aptNm": "교육용 예시 아파트",
      "dealYear": "2026",
      "dealMonth": "1",
      "dealDay": "15",
      "dealAmount": "120,000",
      "excluUseAr": "84.95",
      "floor": "10",
      "cdealType": "",
      "cdealDay": ""
    }
  ],
  "returned_count": 1,
  "has_next": true,
  "units": {"dealAmount": "만원", "excluUseAr": "㎡"},
  "note": "한 페이지의 원본 거래입니다. 취소 거래(cdealType, cdealDay)를 확인하세요. 신고 지연·정정으로 결과가 바뀔 수 있습니다."
}

응답 메타데이터

has_next=true이면 같은 지역·월·페이지 크기로 page를 1 늘려 조회합니다. 조회 중 원천 데이터가 정정되면 페이지별 결과나 건수도 달라질 수 있습니다. 결과가 없다면 items=[], returned_count=0으로 반환될 수 있습니다.

자주 사용하는 거래 필드

원본 조회 도구는 XML 필드의 앞뒤 공백만 제거합니다. 숫자형 변환, 금액 환산, 누락값 보정, 취소 거래 제거, 정렬은 자동 수행하지 않습니다. 분석 도구는 앞서 설명한 수집·제외·계산 규칙을 별도로 적용합니다. API나 거래에 따라 필드가 없거나 빈 문자열일 수 있습니다.

Python과 LangChain에서 사용

아래 예제는 GitHub 저장소 접근 없이, PyPI 패키지만으로 실행할 수 있습니다. 저장소는 현재 비공개이므로 소스 링크는 접근 권한이 있는 사용자만 열 수 있습니다.

1. LLM 없이 MCP 도구 직접 호출

mcp_demo.py라는 파일에 저장합니다. 앞서 설명한 방식으로 PUBLIC_DATA_API_KEY를 터미널에 설정하세요.

import asyncio
import json
import os

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client


async def main():
    params = StdioServerParameters(
        command="uvx",
        args=["--from", "kre-mcp==0.2.0", "kre-mcp"],
        env={"PUBLIC_DATA_API_KEY": os.environ["PUBLIC_DATA_API_KEY"]},
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print("도구:", [tool.name for tool in tools.tools])
            result = await session.call_tool(
                "realestate_search_apt_trade",
                {"region_code": "11680", "deal_ym": "202601", "page_size": 5},
            )
            if result.isError:
                raise RuntimeError(result.content)
            data = json.loads(result.content[0].text)
            print(json.dumps(data, ensure_ascii=False, indent=2))


asyncio.run(main())

uv run --no-project --with "mcp>=1.26,<2" python mcp_demo.py

이 실습에는 LLM API 키가 필요하지 않습니다. 서버 도구가 실제로 동작하는지 먼저 확인하기 좋은 단계입니다.

2. LangChain MCP 어댑터로 에이전트 만들기

MCP 어댑터는 서버의 도구를 LangChain이 호출할 수 있는 도구로 변환합니다. 다음 예제는 기존 langchain-mcp-adapters의 MultiServerMCPClient를 사용하는 교육용 코드입니다.

이 어댑터 저장소는 유지보수가 종료됐으며 공식 후속 API는 langchain.mcp.MCPAdapter입니다. 기존 교육 자료와의 연결을 위해 아래 예제는 검증한 기존 어댑터 버전을 고정합니다.

agent_demo.py로 저장하세요. 공공데이터 키 외에 선택한 LLM 제공자의 키도 필요합니다. 아래 코드는 Anthropic 연동 예시이며, MODEL_ID에는 본인 계정에서 사용할 수 있는 실제 모델 ID를 설정합니다.

import asyncio
import os

from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient


async def main():
    client = MultiServerMCPClient({
        "kre": {
            "transport": "stdio",
            "command": "uvx",
            "args": ["--from", "kre-mcp==0.2.0", "kre-mcp"],
            "env": {"PUBLIC_DATA_API_KEY": os.environ["PUBLIC_DATA_API_KEY"]},
        }
    })
    tools = await client.get_tools()
    agent = create_agent(
        model="anthropic:" + os.environ["MODEL_ID"],
        tools=tools,
        system_prompt=(
            "실거래가 조회 도우미입니다. 도구로 조회하고 한국어로 답하세요. "
            "금액은 만원, 면적은 ㎡입니다. 전체 건수와 현재 페이지 건수를 구분하세요."
        ),
    )
    result = await agent.ainvoke(
        {"messages": [{
            "role": "user",
            "content": "지역코드 11680의 2026년 1월 매매와 분양권 전매를 각각 1건 조회해줘.",
        }]},
        config={"recursion_limit": 12},
    )
    print(result["messages"][-1].content)


asyncio.run(main())

macOS / Linux 환경변수 예시:

export ANTHROPIC_API_KEY='본인의 LLM API 키'
export MODEL_ID='계정에서 사용 가능한 모델 ID'

Windows PowerShell 환경변수 예시:

$env:ANTHROPIC_API_KEY = '본인의 LLM API 키'
$env:MODEL_ID = '계정에서 사용 가능한 모델 ID'

실행 명령은 한 줄입니다.

uv run --no-project --with langchain==1.4.3 --with langchain-mcp-adapters==0.3.2 --with langchain-anthropic python agent_demo.py

LLM API 이용 요금은 모델 제공자의 정책을 따릅니다. 질문과 조회 결과는 선택한 모델 제공자에게 전달됩니다. 공공데이터 키는 서버 환경변수로 전달하고 프롬프트에는 넣지 않습니다.

검증 범위: 기존 어댑터와 테스트용 모델을 이용해 create_agent → MCP 서버 → 실제 국토교통부 API → 도구 결과 → 에이전트 종료 흐름을 검증했습니다. 실제 유료 LLM의 도구 선택·답변 품질까지 검증한 것은 아닙니다.

저장소 접근 권한이 있다면 실행 가능한 에이전트·연결 테스트 예제도 이용할 수 있습니다.

문제 해결

uvx 실행 파일 위치 확인:

# macOS / Linux
command -v uvx

# Windows PowerShell
(Get-Command uvx).Source

문제를 공유할 때는 패키지 버전, 운영체제, 클라이언트, 도구 이름, 키를 제외한 입력값, 오류 메시지를 함께 남겨 주세요. 인증키가 들어 있는 설정 파일 전체를 공유하지 마세요.

자주 묻는 질문

설치만 하면 AI와 대화할 수 있나요?
아니요. 이 패키지는 데이터 조회 서버입니다. 대화하려면 MCP 클라이언트나 LLM 에이전트가 필요합니다. Python에서 직접 호출하면 LLM 없이도 조회할 수 있습니다.

패키지에 API 키가 들어 있나요?
없습니다. 각 사용자가 공공데이터포털에서 키를 발급받아 환경변수로 설정합니다.

무료인가요?
패키지는 MIT 라이선스로 배포됩니다. 공공데이터 API의 이용 조건·호출 한도는 포털을 따르며, AI 클라이언트나 LLM API 비용은 별도입니다.

실거래가가 지금 매물의 가격인가요?
신고된 계약 자료입니다. 현재 호가나 매물 목록을 제공하지 않습니다. 신고 지연·정정·취소로 결과가 바뀔 수 있습니다.

지역 이름만 입력해도 되나요?
realestate_get_region_code가 지역명에서 5자리 코드 후보를 찾습니다. 동명 지역이나 오타 후보는 사용자 확인 후 조회에 사용하세요. 기간도 명시하면 실습을 재현하기 쉽습니다.

전월세나 한국부동산원 통계도 조회할 수 있나요?
전월세 조회와 전세가율 분석은 지원합니다. 한국부동산원 R-ONE 통계·공식 가격지수는 제공하지 않습니다.

업데이트는 어떻게 하나요?
버전을 고정한 클라이언트는 설정의 버전 문자열을 새 릴리스로 바꾸고 재시작하세요. 최신 버전 확인은 uvx --refresh kre-mcp --version, pip 설치 업데이트는 가상환경에서 python -m pip install --upgrade kre-mcp를 사용합니다.

개발·검증·배포

소스 저장소 접근 권한이 있는 개발자는 저장소 루트에서 실행합니다.

uv sync --locked
uv run pytest -q
uv run ruff check .
uv build
uv run twine check dist/*

자동 테스트는 통계 계산, 전세·월세 구분, 주소·면적 매칭, 빈 월 변동률, 전체 페이지 수집 검증, 지역 후보 검색, 입력 검증, XML 응답 파싱, 빈 결과, 오류·인증키 노출 방지, HTTP 요청과 페이지 처리, 실제 stdio MCP 연결을 확인합니다. 일반 테스트에는 API 키가 필요하지 않습니다. 실제 공공데이터 조회는 PUBLIC_DATA_API_KEY를 설정한 뒤 uv run python scripts/smoke_live.py로 8개 도구를 검증합니다. 배포 패키지 검증은 --published를 추가합니다.

지역코드 스냅샷은 uv run python scripts/update_regions.py로 공식 자료를 다시 다운로드해 갱신할 수 있습니다. 생성 파일에 원문 SHA-256과 수집일을 기록합니다.

PyPI 배포는 GitHub Actions의 Publish to PyPI 워크플로에서 진행합니다. main의 버전을 갱신하고 잠금 파일을 반영한 뒤 실행하면 테스트·빌드를 거쳐 pypi 환경의 Trusted Publishing으로 게시합니다. 이미 게시한 버전은 덮어쓰지 않습니다.

변경 이력

• 0.2.0 — 전월세 조회, 전국 지역명·퍼지 검색, 매매 추이, 2~5개 지역 비교, 전세가율, 단지 종합 요약 추가. 전체 페이지 검증·취소 제외·표본수·누락 처리 및 관련 실습 안내 추가.
• 0.1.1 — 사용자·교육생 안내서 확장: 설치, 클라이언트 설정, 단계별 실습, 입력·응답 명세, Python·LangChain 예제, 문제 해결. 서버 도구의 동작은 0.1.0과 동일합니다.
• 0.1.0 — 아파트 매매·분양권 전매 MCP 도구, 페이지 정보, 환경변수 인증, 초기 PyPI 배포.

데이터 출처와 라이선스

• 행정안전부 법정동코드 전체자료 — 현행 코드·명칭 스냅샷
• 국토교통부 아파트 전월세 실거래가 API
• 국토교통부 아파트 매매 실거래가 API
• 국토교통부 아파트 분양권전매 실거래가 API
• 코드: MIT License, Copyright (c) 2026 jaypakdevkr.
• 데이터의 제공 범위·이용 조건은 각 원천 API의 안내를 따릅니다.