한국 부동산 MCP 설치·사용법 — 국토교통부 공공데이터로 아파트·오피스텔·빌라

Q: 어떤 부동산 정보를 조회할 수 있나요?

아파트·오피스텔·빌라(연립다세대) 실거래가, 전월세 내역, 한국부동산원 청약홈 청약 일정, 한국자산관리공사 온비드 공매 물건 정보를 조회할 수 있습니다.

Q: Claude Desktop과 Cursor 중 어디서 쓸 수 있나요?

두 클라이언트 모두 MCP stdio 방식을 지원하므로 같은 설정으로 사용 가능합니다. Cursor는 .cursor/mcp.json, Claude Desktop은 claude_desktop_config.json에 서버를 등록합니다.

Q: 실거래가 데이터는 얼마나 최신인가요?

국토교통부 실거래가 공공데이터는 통상 거래 신고 후 30일 이내 업데이트됩니다. 최신 시세가 아닌 신고된 실거래가 기준이므로 참고용으로 활용하세요.

Q: API 호출 한도가 있나요?

data.go.kr 일반 공개 API는 기본적으로 일 1,000건 한도가 있습니다. 더 많은 호출이 필요하면 포털에서 활용 신청 시 사용 목적을 기재해 한도 증량을 요청할 수 있습니다.

한국 부동산 MCP(Korea Real Estate MCP)를 Claude나 Cursor에 설치하면, 채팅 한 줄로 국토교통부 실거래가·청약홈·온비드 데이터를 직접 조회할 수 있습니다. 별도 웹사이트를 오가거나 엑셀을 열 필요 없이 AI가 데이터를 가져와 분석까지 이어줍니다. 이 가이드는 API 키 발급부터 Claude Desktop 연결, 첫 조회 확인까지 전 과정을 단계별로 안내합니다.

한국 부동산 MCP가 필요한 이유

부동산 투자·임장·청약 준비를 할 때 가장 번거로운 작업 중 하나가 데이터 수집입니다. 국토교통부 실거래가 공개시스템, 한국부동산원 청약홈, 한국자산관리공사 온비드(공매)는 모두 별도 사이트에 흩어져 있어, 단지별 시세 변화를 파악하거나 청약 일정과 매매 시세를 함께 보려면 탭을 여러 개 열어야 합니다.

Korea Real Estate MCP는 이 세 가지 데이터 소스를 MCP 서버로 감싸, Claude나 Cursor 같은 AI 도구에서 자연어 질의 한 번으로 결과를 받아볼 수 있게 해줍니다. “서울 마포구 아현동 아파트 2024년 실거래가 평균 알려줘”처럼 물어보면 AI가 API를 호출해 데이터를 가져와 표로 정리해 줍니다.

데이터 흐름 한눈에 보기

사용자 질문 (Claude / Cursor)
        │
        ▼
 Korea Real Estate MCP (stdio)
        │
        ├─▶ 국토교통부 실거래가 API (data.go.kr)
        ├─▶ 한국부동산원 청약홈
        └─▶ 한국자산관리공사 온비드

MCP 서버는 로컬에서 실행되며, AI 클라이언트가 stdio를 통해 명령을 전달하면 서버가 각 공공 API에 요청하고 응답을 AI에 돌려줍니다.

준비물

설치 전에 아래 항목을 먼저 확인하세요.

항목	버전/조건	비고
Python	3.10 이상	`python --version`으로 확인
Git	최신 권장	저장소 클론용
Claude Desktop 또는 Cursor	최신 버전	MCP stdio 지원 클라이언트
data.go.kr 계정	무료	API 키 발급 필수
국토교통부 실거래가 API 서비스 키	발급 후 사용	승인 1~2일 소요

단계별 설치 방법

1단계 — 공공데이터포털 API 키 발급

국토교통부 실거래가 공공데이터 API는 data.go.kr에서 무료로 신청할 수 있습니다.

https://www.data.go.kr/data/15126469/openapi.do 에 접속합니다.
오른쪽 상단 활용신청 버튼을 클릭합니다.
로그인 후 신청 목적(예: 개인 학습·연구)을 입력하고 제출합니다.
승인 완료 후 마이페이지 → 개발계정 → 서비스 키에서 발급된 키를 복사해 둡니다.

일반 신청은 자동 승인 또는 1~2 영업일 내 승인됩니다.

2단계 — 저장소 복제 및 의존성 설치

터미널(macOS/Linux) 또는 PowerShell(Windows)에서 아래 명령을 실행합니다.

git clone https://github.com/tae0y/real-estate-mcp
cd real-estate-mcp
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

가상환경을 활성화하면 프롬프트 앞에 (.venv)가 표시됩니다. 이 상태에서 pip install을 실행해야 의존성이 올바른 위치에 설치됩니다.

3단계 — 환경변수 설정

저장소 루트에 .env 파일을 생성하고 발급받은 서비스 키를 입력합니다.

# .env
DATA_GO_KR_API_KEY=여기에_발급받은_서비스키_입력

서비스 키를 코드에 직접 넣지 말고, 반드시 .env 파일에 분리해서 관리하세요. .gitignore에 .env가 포함되어 있는지도 확인하세요.

4단계 — Claude Desktop에 MCP 서버 등록

Claude Desktop의 설정 파일을 열어 서버를 추가합니다. 설정 파일 위치는 아래와 같습니다.

운영체제	경로
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

파일을 열어 mcpServers 항목에 아래 내용을 추가합니다. real-estate-mcp가 처음이면 전체 구조를 참고하세요.

{
  "mcpServers": {
    "real-estate-mcp": {
      "command": "/절대경로/real-estate-mcp/.venv/bin/python",
      "args": ["-m", "real_estate_mcp"],
      "env": {
        "DATA_GO_KR_API_KEY": "여기에_발급받은_서비스키_입력"
      }
    }
  }
}

주의사항:

command의 경로는 반드시 절대 경로로 작성해야 합니다. ~/로 시작하는 상대 경로는 인식되지 않을 수 있습니다.
macOS 기준 예시: /Users/사용자명/projects/real-estate-mcp/.venv/bin/python
Windows 기준 예시: C:/Users/사용자명/projects/real-estate-mcp/.venv/Scripts/python.exe

Cursor를 사용하는 경우 .cursor/mcp.json에 동일한 형식으로 추가합니다.

{
  "mcpServers": {
    "real-estate-mcp": {
      "command": "/절대경로/real-estate-mcp/.venv/bin/python",
      "args": ["-m", "real_estate_mcp"],
      "env": {
        "DATA_GO_KR_API_KEY": "여기에_발급받은_서비스키_입력"
      }
    }
  }
}

5단계 — 연결 확인 및 첫 조회

Claude Desktop을 완전히 종료한 후 다시 실행합니다. 채팅창에서 아래와 같이 입력해 보세요.

서울 마포구 아현동 아파트 2024년 실거래가를 조회해줘

Claude가 real-estate-mcp 도구를 사용해 데이터를 가져온 후 결과를 표로 정리해 준다면 설치에 성공한 것입니다.

조회 가능한 데이터 종류

Korea Real Estate MCP가 연결하는 세 가지 데이터 소스를 정리하면 다음과 같습니다.

데이터 소스	주요 조회 내용	갱신 주기
국토교통부 실거래가 (data.go.kr)	아파트·오피스텔·빌라 매매·전월세 실거래가	신고 후 ~30일
한국부동산원 청약홈	청약 공고·일정·당첨자 발표	수시
한국자산관리공사 온비드	공매 물건 목록·입찰 일정	수시

흔한 오류와 해결 방법

”API 키가 유효하지 않습니다” 오류

data.go.kr에서 발급된 서비스 키에는 인코딩된 특수문자(%2B 등)가 포함될 수 있습니다. .env 파일에 붙여넣기할 때는 URL 디코딩된 원래 값을 사용해야 합니다. 포털 마이페이지에서 키를 복사할 때 일반 인증키(Decoding) 항목의 값을 사용하세요.

MCP 서버가 Claude에서 보이지 않는 경우

claude_desktop_config.json 파일의 JSON 문법을 검증하세요. 쉼표 누락이나 따옴표 불일치가 흔한 원인입니다.
Python 절대 경로가 올바른지 확인합니다. 터미널에서 which python(macOS/Linux) 또는 where python(Windows)으로 경로를 재확인하세요.
가상환경 내부의 Python을 지정했는지 확인합니다. 시스템 Python을 가리키면 패키지를 찾지 못합니다.

데이터가 오래됐거나 없는 경우

실거래가 데이터는 거래 신고 후 약 30일이 지나야 반영됩니다. 최근 거래는 아직 시스템에 없을 수 있으므로, 조회 기간을 좀 더 이전으로 설정해서 확인해 보세요.

활용 예시

한국 부동산 MCP를 활용하면 아래와 같은 분석을 Claude와의 대화만으로 처리할 수 있습니다.

매수 타이밍 분석: “강남구 대치동 은마아파트 최근 3년 실거래가 추이를 표로 보여줘”
청약 준비: “다음 달 서울 청약 공고 목록과 분양가 알려줘”
공매 물건 탐색: “경기도 수원시 아파트 온비드 공매 물건 있어?”
지역 비교: “마포구와 성동구 오피스텔 전세 평균 비교해줘”

자주 묻는 질문

한국 부동산 MCP를 사용하려면 반드시 API 키가 필요한가요?

네, 국토교통부 실거래가 공공데이터 API 키가 필요합니다. data.go.kr에서 무료로 신청할 수 있으며, 승인까지 보통 1~2일이 소요됩니다. 청약홈·온비드 일부 기능은 공개 데이터라 키 없이 조회될 수 있지만, 실거래가는 반드시 키가 필요합니다.

어떤 부동산 정보를 조회할 수 있나요?

아파트·오피스텔·빌라(연립다세대) 매매 및 전월세 실거래가, 한국부동산원 청약홈 청약 공고 및 일정, 한국자산관리공사 온비드 공매 물건 정보를 조회할 수 있습니다. 데이터의 구체적인 제공 범위는 공식 저장소의 README를 확인하세요.

Claude Desktop과 Cursor 중 어디서 쓸 수 있나요?

두 클라이언트 모두 MCP stdio 방식을 지원하므로 사실상 같은 설정으로 사용 가능합니다. Cursor는 프로젝트 루트의 .cursor/mcp.json에, Claude Desktop은 운영체제 앱 데이터 폴더의 claude_desktop_config.json에 서버 정보를 등록하면 됩니다.

실거래가 데이터는 얼마나 최신인가요?

국토교통부 실거래가 공공데이터는 통상 거래 신고 후 30일 이내에 업데이트됩니다. 실거래가 신고 의무 기한이 계약일로부터 30일이므로 최신 거래는 한 달 정도 지연될 수 있습니다. 시세 참고용으로 활용하시되, 계약 시에는 공인중개사나 실제 시장 확인을 병행하세요.

Windows에서도 설치할 수 있나요?

Python 3.10 이상과 Git이 설치되어 있다면 Windows PowerShell에서도 동일한 방법으로 설치할 수 있습니다. 가상환경 활성화 명령이 .venv\Scripts\activate로 다르고, Python 실행 파일 경로가 .venv\Scripts\python.exe임에 주의하세요.

API 호출 한도가 있나요?

data.go.kr 일반 공개 API는 기본적으로 일 1,000건 한도가 적용됩니다. 대량 조회가 필요하면 포털 활용 신청 시 사용 목적과 예상 호출량을 기재해 한도 증량을 요청할 수 있습니다. 개인 학습·소규모 프로젝트는 대부분 기본 한도 안에서 충분합니다.