국토부 실거래가 API를 Claude에 연결하기 (real-estate-mcp 설치 가이드)

국토교통부 실거래가 공공 API를 Claude에 MCP로 연결하면, “강남구 아파트 올해 실거래가 추이 보여줘”라는 한 문장으로 데이터를 바로 받아볼 수 있습니다. 이 글에서는 실제로 동작하는 오픈소스 서버 real-estate-mcp를 기준으로, API 키 발급 → 저장소 클론 → Claude Desktop 설정 → 동작 확인까지 전 과정을 단계별로 안내합니다. 코드를 직접 작성할 필요는 없습니다.

이 가이드의 핵심 사실 요약

• 서버: tae0y/real-estate-mcp (GitHub, 직접 클론 방식 — npx·uvx 미지원)
• 데이터 출처: 국토교통부 실거래가 API (data.go.kr)
• 실행 환경: Python 3.10 이상 + uv(권장) 또는 pip
• 연결 대상: Claude Desktop / Claude Code / Cursor 등 MCP 클라이언트

직접 API를 쓰는 것과 무엇이 다른가

국토교통부 실거래가 API를 코드로 직접 호출하려면 OpenAPI 규격 파악, 인증키 처리, JSON 파싱을 매번 직접 작성해야 합니다. MCP(Model Context Protocol) 서버를 한 번 연결해 두면, 같은 작업을 Claude 채팅창에서 자연어로 반복할 수 있습니다.

real-estate-mcp를 연결하면 다음과 같은 질의가 가능합니다.

• 특정 지역·기간의 아파트 실거래가 조회
• 매물 호가와 실거래가 비교
• 매수 시나리오별 대출·세금 계산 (서버 지원 기능 범위 내)

이 글에서 다루는 한국 부동산 MCP는 공공데이터포털(data.go.kr)의 국토교통부 실거래가 API를 기반으로 하며, 아파트뿐 아니라 오피스텔·연립·다세대(빌라) 데이터도 지원합니다.

데이터 흐름 한눈에 보기

사용자 (자연어 질문)
        │
        ▼
Claude Desktop / Claude Code / Cursor
        │  MCP 프로토콜 (stdio)
        ▼
real-estate-mcp 서버 (로컬 Python 프로세스)
        │  HTTP 요청 + 인증키
        ▼
국토교통부 실거래가 API (data.go.kr)
        │  JSON 응답
        ▼
MCP 서버 → Claude → 자연어 답변

클라이언트와 MCP 서버는 stdio 방식으로 통신하고, 외부 API 호출은 로컬에서 실행되는 서버가 담당합니다. 따라서 인증키는 로컬 환경 변수에만 저장되며 Claude 클라우드 서버로 전달되지 않습니다.

준비물 체크리스트

항목	설명
data.go.kr 계정	공공데이터포털 회원가입 (무료)
국토교통부 실거래가 API 키	아래 1단계에서 발급
Python 3.10 이상	real-estate-mcp 실행 환경
uv 또는 pip	Python 패키지 관리
Claude Desktop	MCP 클라이언트 (또는 Claude Code·Cursor)
Git	저장소 클론용

단계별 설치 및 설정

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

data.go.kr 국토교통부 실거래가 API 페이지에 접속합니다.

1. data.go.kr에 로그인합니다 (계정이 없으면 무료 회원가입).
2. API 상세 페이지에서 [활용신청] 버튼을 클릭합니다.
3. 활용 목적 등 간단한 정보를 입력하고 신청합니다. 대부분 즉시 자동 승인됩니다.
4. 마이페이지 → 오픈API → 개발계정으로 이동해 발급된 일반 인증키(서비스 키) 를 복사합니다.

인증키는 인코딩 키와 디코딩 키 두 가지가 함께 제공됩니다. Python 환경에서는 디코딩 키를 사용하는 경우가 많으니, 어느 쪽을 넣을지는 서버 README를 확인하세요. (인증 오류의 흔한 원인이므로 메모해 두는 것을 권장합니다.)

2단계: real-estate-mcp 저장소 클론

터미널에서 저장소를 클론합니다.

git clone https://github.com/tae0y/real-estate-mcp.git
cd real-estate-mcp

의존성은 uv(권장) 또는 pip으로 설치합니다.

# uv를 사용하는 경우 (권장)
uv sync

# pip을 사용하는 경우
pip install -e .

설치가 끝나면 서버가 정상 기동되는지 먼저 확인합니다.

# uv 환경에서 실행 테스트
uv run python -m real_estate_mcp

오류 없이 대기 상태가 되면 정상입니다. 확인 후 Ctrl+C로 종료합니다. (이 명령은 어디까지나 설치 점검용이며, 실제 사용 시에는 Claude Desktop이 자동으로 서버를 실행합니다.)

3단계: Claude Desktop 설정 파일 수정

Claude Desktop의 MCP 설정 파일을 편집합니다.

설정 파일 위치

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

아래 내용을 추가합니다. --directory 뒤 경로는 클론한 실제 경로로, env의 값은 발급받은 인증키로 바꿔야 합니다.

{
  "mcpServers": {
    "real-estate-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/여기에/클론한/경로/real-estate-mcp",
        "run",
        "python",
        "-m",
        "real_estate_mcp"
      ],
      "env": {
        "DATA_GO_KR_API_KEY": "발급받은_서비스_디코딩_키"
      }
    }
  }
}

uv 대신 pip 환경을 사용한다면 command를 python으로 바꾸고 args를 해당 Python 실행 환경에 맞게 조정하세요.

Claude Code나 Cursor를 쓴다면 위와 동일한 mcpServers 블록을 각 클라이언트의 MCP 설정 파일에 넣으면 됩니다. 파일 경로만 다를 뿐 형식은 같습니다.

4단계: Claude Desktop 재시작 및 연결 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 시작합니다. 창만 닫는 것이 아니라 앱 자체를 종료해야 합니다(macOS는 Cmd+Q).

재시작 후 채팅창 하단의 도구(망치) 아이콘을 클릭해 real-estate-mcp 도구가 목록에 나타나는지 확인합니다. 도구가 보이면 연결 성공입니다.

5단계: 자연어로 실거래가 조회

이제 Claude 채팅창에서 자연어로 질의합니다.

# 예시 질의
강남구 아파트 2025년 실거래가 평균 알려줘.
마포구 오피스텔 최근 3개월 실거래가 목록을 표로 정리해줘.
송파구 빌라 전용면적 60㎡ 기준 최근 거래 사례 찾아줘.

Claude가 MCP 도구를 호출해 국토교통부 API에서 데이터를 가져온 뒤 요약·분석해 답변합니다.

흔한 오류와 해결 방법

증상	주된 원인	해결
도구 목록에 안 보임	설정 파일 경로 오류 / 미재시작	JSON 문법(쉼표·중괄호), --directory 경로 확인 후 완전 재시작
인증 오류 (401/403)	키 오입력 / 승인 미완료	키 승인 상태, 디코딩·인코딩 키 구분, 환경 변수명 확인
실행 실패	Python 버전 미달	python --version으로 3.10 이상 확인
데이터 안 옴	일일 호출 한도 초과	운영계정 전환 신청 또는 다음 날 재시도

”도구를 찾을 수 없음” 오류

설정 파일 경로가 잘못됐거나 Claude Desktop이 완전히 재시작되지 않은 경우입니다.

• 설정 파일의 JSON 문법 오류(쉼표·중괄호 누락)를 확인합니다.
• --directory 뒤 경로가 실제 클론 위치와 일치하는지 확인합니다.
• Claude Desktop을 완전 종료 후 재시작합니다.

API 호출 시 인증 오류 (401/403)

API 키가 잘못 입력됐거나 승인이 완료되지 않은 경우입니다.

• data.go.kr 마이페이지에서 키가 승인 상태인지 확인합니다. 자동 승인이라도 수 분이 걸릴 수 있습니다.
• 디코딩 키·인코딩 키를 혼동하지 않았는지 확인합니다.
• 환경 변수명이 서버 README에 명시된 변수명과 정확히 일치하는지 확인합니다.

Python 버전 오류

real-estate-mcp는 Python 3.10 이상을 권장합니다. python --version으로 버전을 확인하고 필요하면 업그레이드합니다.

일일 호출 한도 초과

개발계정에는 일일 호출 한도가 있습니다. 한도를 초과하면 data.go.kr에서 운영계정 전환을 신청하거나 다음 날 다시 시도합니다.

함께 활용하면 좋은 MCP 서버

부동산 분석을 확장하려면 아래 서버를 함께 연결해 보세요.

서버	활용 시나리오
공공데이터포털 MCP 서버 모음	국민연금·금융감독원 등 다른 공공 API를 추가로 연결할 때
표준국어대사전 MCP 서버	부동산 용어·법령 표현을 정확하게 확인할 때

공공데이터 카테고리에서 더 많은 한국 공공데이터 MCP 서버를 찾아볼 수 있습니다.

자주 묻는 질문

공공데이터포털 API 키는 유료인가요?

아니요. data.go.kr의 공공 API 인증키는 무료입니다. 회원가입 후 해당 API에 활용신청을 하면 대부분 자동 승인됩니다. 단, 일일 호출 횟수 한도가 있으며 대량 호출이 필요하면 운영계정으로 전환 신청을 해야 합니다.

real-estate-mcp는 npx로 바로 설치할 수 있나요?

아니요. 현재 real-estate-mcp는 npm·uvx 패키지로 배포되지 않아 npx·uvx로 바로 실행할 수 없습니다. GitHub 저장소를 직접 클론한 뒤 로컬에서 실행해야 합니다(2단계 참고).

아파트 외에 오피스텔·빌라 실거래가도 조회할 수 있나요?

네. real-estate-mcp는 국토교통부 공공데이터를 기반으로 아파트뿐 아니라 오피스텔·연립·다세대(빌라) 실거래가도 지원합니다. 지원 범위는 서버 업데이트에 따라 달라질 수 있으니 GitHub 저장소 README를 확인하세요.

Claude Code와 Cursor에서도 쓸 수 있나요?

네. MCP 표준을 지원하는 모든 클라이언트에서 동작합니다. Claude Desktop·Claude Code·Cursor 모두 동일한 mcpServers 설정으로 연결하며, 클라이언트별로 설정 파일 경로만 다릅니다(3단계 참고).

API 키가 노출되면 어떻게 해야 하나요?

즉시 data.go.kr 마이페이지에서 해당 API 인증키를 재발급하세요. 키는 코드나 공개 저장소에 절대 포함하지 말고, 환경 변수나 별도 .env 파일로 관리하는 것이 원칙입니다.

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

국토교통부 실거래가 공공데이터는 통상 신고일 기준 30일 이내에 API에 반영됩니다. 부동산 거래 신고 기한(계약 후 30일) 특성상, 가장 최근 1~2개월 데이터는 계속 갱신됩니다.

다음 단계

연결을 마쳤다면 시세 조회에서 시작해 매수 타이밍 분석, 지역별 가격 비교까지 자연어로 다뤄 보세요.

더 많은 한국 공공데이터 MCP 서버는 공공데이터 카테고리와 전체 서버 목록에서 확인할 수 있습니다. 새로운 MCP 서버를 발견했다면 서버 제출로 MCP모아에 등록해 주세요.