부동산 실거래가 MCP 연동 — 국토부 API로 Claude 시세 조회하기

Q: API 응답 데이터가 XML인데 MCP에서 어떻게 처리하나요?

국토부 API는 기본적으로 XML 형식으로 응답합니다. MCP 서버 측에서 XML을 JSON으로 파싱한 뒤 MCP 도구 결과로 반환하므로, Claude는 구조화된 데이터를 받아 자연어로 해석합니다.

Q: Claude Desktop이 아닌 Cursor나 VS Code에서도 사용할 수 있나요?

MCP를 지원하는 모든 클라이언트에서 동일한 서버 설정으로 사용할 수 있습니다. Cursor는 .cursor/mcp.json, VS Code Copilot은 .vscode/mcp.json 파일에 같은 형식의 서버 항목을 추가하면 됩니다.

국토교통부 실거래가 API를 MCP(Model Context Protocol)로 Claude에 연결하면, 별도의 웹 검색 없이 Claude 대화창에서 직접 “서울 강남구 아파트 실거래가”를 자연어로 물어볼 수 있습니다. 이 가이드는 공공데이터포털 API 키 발급부터 Claude Desktop 연동, 흔한 오류 해결까지 한 번에 다룹니다. 전체 과정은 약 20~30분 이내에 완료할 수 있습니다.

왜 부동산 실거래가 MCP가 필요한가

부동산 시세를 파악할 때 가장 신뢰할 수 있는 공식 데이터는 국토교통부 실거래가 공개시스템(rt.molit.go.kr)입니다. 하지만 웹사이트에서 단지·지역·기간을 일일이 필터링하는 작업은 번거롭고, 여러 지역을 비교하거나 추세를 분석하려면 반복 작업이 늘어납니다.

MCP를 통해 Claude에 실거래가 API를 연결하면 다음과 같은 흐름으로 동작합니다.

사용자(자연어 질문)
    ↓
Claude Desktop / Cursor (MCP 클라이언트)
    ↓  MCP 도구 호출
실거래가 MCP 서버 (로컬 프로세스)
    ↓  HTTP 요청
국토교통부 실거래가 Open API (data.go.kr)
    ↓  XML 응답 → JSON 파싱
MCP 서버 → Claude → 자연어 답변

Claude가 도구를 직접 호출하기 때문에, “2025년 하반기 마포구 아파트 평균 실거래가를 표로 정리해줘”라는 요청 하나로 데이터 조회·정리·분석을 한 번에 처리할 수 있습니다.

준비물 체크리스트

항목	내용
공공데이터포털 계정	data.go.kr 회원가입(무료)
국토부 실거래가 API 키	포털에서 신청 후 승인(수 시간~1일)
Node.js 18 이상	MCP 서버 실행 환경
Claude Desktop 최신 버전	MCP 클라이언트 역할
텍스트 에디터	설정 파일 수정용

단계별 연동 방법

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

data.go.kr에 로그인합니다.
검색창에 “국토교통부 아파트매매 실거래가 상세 자료” 를 검색합니다.
해당 데이터셋 상세 페이지에서 활용신청 버튼을 클릭합니다.
활용 목적을 간략히 작성하고 신청을 완료합니다.
승인 후 마이페이지 → 개발계정 탭에서 인증키(Encoding 키)를 복사합니다.

참고: 국토부 API는 아파트 외에도 연립·다세대, 오피스텔, 단독·다가구, 토지 등 별도 API가 있습니다. 필요한 유형은 각각 신청해야 합니다.

2단계: MCP 서버 준비

국토교통부 실거래가 API를 MCP 도구로 래핑하는 서버를 준비합니다. 현재 MCP모아 디렉토리에 등록된 공식 실거래가 전용 서버는 없으므로, 직접 간단한 서버를 구성하거나 GitHub에서 커뮤니티 프로젝트를 탐색합니다.

직접 구성하는 경우 아래 예시 구조를 참고하세요.

mkdir molit-mcp && cd molit-mcp
npm init -y
npm install @modelcontextprotocol/sdk axios xml2js dotenv

프로젝트 루트에 .env 파일을 만들고 API 키를 저장합니다.

# .env
MOLIT_API_KEY=여기에_발급받은_인증키_붙여넣기

3단계: MCP 서버 핵심 코드 작성

index.js 파일을 생성하고 아래 구조로 작성합니다.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import axios from "axios";
import { parseStringPromise } from "xml2js";
import "dotenv/config";

const server = new McpServer({ name: "molit-realprice", version: "1.0.0" });

server.tool(
  "get_apartment_trade",
  "국토교통부 아파트 실거래가 조회",
  {
    lawd_cd: { type: "string", description: "법정동 코드 앞 5자리 (예: 11680 = 강남구)" },
    deal_ymd: { type: "string", description: "계약년월 YYYYMM (예: 202501)" },
  },
  async ({ lawd_cd, deal_ymd }) => {
    const url = "http://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev/getRTMSDataSvcAptTradeDev";
    const res = await axios.get(url, {
      params: {
        serviceKey: process.env.MOLIT_API_KEY,
        LAWD_CD: lawd_cd,
        DEAL_YMD: deal_ymd,
        numOfRows: 100,
      },
    });
    const parsed = await parseStringPromise(res.data);
    const items = parsed?.response?.body?.[0]?.items?.[0]?.item ?? [];
    return { content: [{ type: "text", text: JSON.stringify(items, null, 2) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

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

Claude Desktop의 설정 파일 위치는 운영체제에 따라 다릅니다.

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

파일을 열어 mcpServers 항목에 아래 내용을 추가합니다.

{
  "mcpServers": {
    "molit-realprice": {
      "command": "node",
      "args": ["/절대경로/molit-mcp/index.js"],
      "env": {
        "MOLIT_API_KEY": "여기에_발급받은_인증키"
      }
    }
  }
}

경로는 반드시 절대 경로로 지정하고, Windows에서는 역슬래시(\) 대신 슬래시(/)를 사용하거나 역슬래시를 두 번(\\) 씁니다.

5단계: Claude Desktop 재시작 및 테스트

Claude Desktop을 완전히 종료한 뒤 다시 실행합니다. 대화창에서 다음과 같이 질문해 보세요.

“서울 강남구(법정동 코드 11680) 2025년 1월 아파트 실거래 내역을 알려줘.”
“2025년 6월 마포구 실거래가 평균을 계산해줘.”

Claude가 MCP 도구를 호출해 국토부 API에서 데이터를 가져오고, 자연어로 요약·분석한 결과를 돌려줍니다.

법정동 코드 조회 방법

국토부 API에서 지역 지정에 필요한 법정동 코드 5자리는 행정안전부 공공데이터에서 확인할 수 있습니다. 주요 지역 코드 예시는 다음과 같습니다.

지역	법정동 코드(5자리)
서울 강남구	11680
서울 마포구	11440
서울 송파구	11710
경기 성남시 분당구	41135
부산 해운대구	26350

전체 코드 목록은 공공데이터포털에서 “법정동코드” 검색 후 CSV 파일로 내려받을 수 있습니다.

흔한 오류와 해결 방법

”SERVICE_KEY_IS_NOT_REGISTERED_ERROR”

공공데이터포털에서 해당 API를 아직 신청하지 않았거나 승인 대기 중입니다. 마이페이지 → 개발계정에서 승인 상태를 확인하세요. 신청 직후에는 수 시간이 걸릴 수 있습니다.

MCP 도구가 Claude에 표시되지 않음

claude_desktop_config.json 파일에 JSON 문법 오류가 있는지 확인합니다. 터미널에서 아래 명령으로 검증할 수 있습니다.

node -e "require('./claude_desktop_config.json')" && echo "JSON 유효"

또한 서버 파일 경로가 절대 경로인지, 파일이 실제로 해당 위치에 존재하는지 재확인하세요.

API 응답이 빈 배열

조회 기간이 너무 이르거나(데이터 없음), 법정동 코드 형식이 잘못됐을 수 있습니다. 코드는 반드시 5자리 숫자여야 하며, 6자리 이상이면 앞 5자리만 사용합니다. 또한 당월·직전월 거래는 신고 기한(30일) 때문에 아직 반영되지 않을 수 있습니다.

Node.js 버전 오류

@modelcontextprotocol/sdk는 ES Module(import) 문법을 사용합니다. package.json에 "type": "module"이 설정되어 있어야 하며, Node.js 18 이상 환경이 필요합니다.

{
  "type": "module"
}

자주 묻는 질문

국토교통부 실거래가 API는 유료인가요?

공공데이터포털(data.go.kr)에서 제공하는 국토교통부 실거래가 API는 회원가입 후 무료로 신청·사용할 수 있습니다. 단, 일일 호출 한도가 있으며 대량 조회 시 트래픽 정책을 확인해야 합니다.

어떤 부동산 유형의 실거래가를 조회할 수 있나요?

국토교통부 실거래가 공개시스템은 아파트, 연립·다세대, 단독·다가구, 오피스텔, 토지, 상업업무용 부동산 등 다양한 유형의 거래 데이터를 API로 제공합니다. 유형별로 별도 API 엔드포인트가 있으므로, 각각 신청이 필요합니다.

API 응답 데이터가 XML인데 MCP에서 어떻게 처리하나요?

국토부 API는 기본적으로 XML 형식으로 응답합니다. MCP 서버 측에서 xml2js 같은 라이브러리로 XML을 JSON으로 파싱한 뒤 MCP 도구 결과로 반환하므로, Claude는 구조화된 데이터를 받아 자연어로 해석합니다.

Claude Desktop이 아닌 Cursor나 VS Code에서도 사용할 수 있나요?

MCP를 지원하는 모든 클라이언트에서 동일한 서버 설정으로 사용할 수 있습니다. Cursor는 .cursor/mcp.json, VS Code Copilot은 .vscode/mcp.json 파일에 같은 형식의 서버 항목을 추가하면 됩니다.

실거래가 데이터의 최신성은 어느 정도인가요?

국토교통부는 계약 후 30일 이내에 신고된 거래 자료를 바탕으로 데이터를 갱신합니다. 따라서 당월 또는 직전 월 거래는 아직 반영되지 않을 수 있습니다.

MCP 서버 구동 중 ‘Invalid API Key’ 오류가 나면 어떻게 하나요?

공공데이터포털에서 발급된 인증키가 활성화(승인 완료)되었는지 확인하세요. 신청 직후에는 수 시간~1일 정도 활성화 대기 시간이 있습니다. 또한 .env 파일의 변수명과 서버 코드에서 읽는 키 이름이 정확히 일치하는지 점검하세요.

다음 단계

이 가이드로 국토부 실거래가 데이터를 Claude에 연동했다면, 다음과 같은 활용으로 확장해 보세요.

법령 연동: 한국 법령 MCP를 추가 연결하면 “이 단지의 용도지역과 건폐율은?”처럼 법령과 시세를 함께 분석할 수 있습니다.
다중 지역 비교: 여러 법정동 코드를 반복 조회해 지역별 평균가 비교표를 Claude에서 자동 생성합니다.
서버 등록: 직접 만든 실거래가 MCP 서버를 오픈소스로 공개하고 MCP모아에 등록하면 커뮤니티와 함께 개선할 수 있습니다.

/guides 에서 더 많은 한국 공공 API MCP 연동 가이드를 확인해 보세요.