국토교통부 실거래가 조회 MCP 서버 (MOLIT Real Estate Transactions MCP Server)

자연어 프롬프트(예: "중구 광희동의 최근 12개월 토지거래 사례를 알려줘")를 받아 국토교통부 실거래가 공개 API를 조회하고, 자산 성격 / 규모(㎡ 및 평) / 거래금액 / 평단가(만원/평) 등을 정형화된 표와 요약 통계로 반환하는 원격 MCP 서버입니다.

---

🛠️ 기술 스택 및 연동 API

• 언어: Python 3.11+ (Python 3.14 호환 완료)
• MCP 프레임워크: FastMCP (Streamable-HTTP transport, /mcp 엔드포인트) 및 SSE 동시 지원
• 데이터 소스: 공공데이터포털 (data.go.kr) 국토교통부 실거래가 오픈 API 3종
  1. 토지 매매 실거래가: RTMSDataSvcLandTrade
  2. 상업업무용 부동산 매매 실거래가: RTMSDataSvcNrgTrade
  3. 아파트 매매 실거래가 상세자료: RTMSDataSvcAptTradeDev

---

✨ 핵심 처리 특징

1. 경량/정적 법정동 코드 매핑:
   • 행정표준코드 데이터 (code_bdong.json)를 프로젝트 내에 정적으로 내장하여, 시도+시군구+법정동명을 5자리 지역코드(LAWD_CD)로 변환합니다.
   • 외부 pandas나 라이브러리 의존성 없이 순수 파이썬 표준 라이브러리만으로 고성능 검색 및 중의적 주소(동명 중복) 확인을 지원합니다.
2. 지분 및 해제 거래 스크리닝:
   • 평단가 왜곡을 방지하기 위해 지분 거래(shareDealingType) 및 계약 해제건(cdealDay, cdealType)을 통계에서 완벽히 분리하고, 필터링 여부에 따라 플래그 표시합니다.
3. 상업업무용 이중 평단가:
   • 상업용 부동산의 특성을 고려하여 대지면적 기준 평단가와 연면적(건물면적) 기준 평단가를 이중으로 산출하여 병기합니다.
4. 거래 희소성 대응 폴백(Fallback):
   • 조회 기간 동안 거래 실적이 0건인 경우, 자동으로 검색 기간을 연장(months_back 증가)하거나 인접 법정동 조회를 검토하라는 제안 메시지를 반환합니다.
5. 보안성:
   • 에러 로그나 디버깅 메시지 출력 시 MOLIT_SERVICE_KEY가 외부로 노출되지 않도록 마스킹 처리 유틸리티가 통합되어 있습니다.

---

🚀 로컬 실행 방법

1. 가상환경 설정 및 의존성 설치

# 가상환경 생성
python -m venv .venv

# 가상환경 활성화 (Windows)
.venv\Scripts\activate

# 서버 구동용 의존성 설치
pip install -r requirements.txt

# (선택) 테스트 스크립트까지 실행하려면 개발용 의존성 추가 설치
pip install -r requirements-dev.txt

requirements.txt는 서버 구동에 필요한 최소 런타임 의존성만 담고 있습니다. test_api.py 등 검증 스크립트는 requests를 사용하므로 requirements-dev.txt로 별도 설치합니다.

2. 환경 변수 설정

프로젝트 루트 폴더에 .env 파일을 생성하고 공공데이터포털에서 발급받은 일반 인증키(Decoding 키 권장)를 설정합니다.

# 국토교통부 실거래가 공개 API 인증키 (공공데이터포털 일반 인증키)
MOLIT_SERVICE_KEY=your_decoding_service_key_here

# 서버 구동 포트
PORT=8080

3. 로컬 테스트 및 API 검증

연결성 및 툴 작동 여부를 사전에 자가진단할 수 있는 통합 검증 스크립트를 제공합니다.

# 로컬 통합 테스트 실행 (requirements-dev.txt 설치 필요)
.venv\Scripts\python.exe test_api.py

4. 로컬 서버 기동

• HTTP/SSE 원격 모드 (클라우드 배포 시 사용):

  .venv\Scripts\python.exe server.py
  

  이 모드에서는 0.0.0.0:8080 포트로 HTTP/SSE 서버가 실행되며, /mcp 엔드포인트로 커넥터를 구성할 수 있습니다.
• Stdio 로컬 파이프 모드 (Claude Desktop 로컬 연동 시 사용):

  .venv\Scripts\python.exe server.py stdio
  

---

☁️ 클라우드타입(Cloudtype) 배포 방법

이 프로젝트는 클라우드타입의 Python Web App 배포를 지원하도록 패키징되어 있습니다.

1. GitHub 저장소 연동: 본 코드를 GitHub 리포지토리(main 브랜치)에 푸시합니다.
2. 클라우드타입 새 프로젝트 생성:
   • 종류: Python
   • 빌드 명령: pip install -r requirements.txt
   • 실행 명령: 비워두면 Procfile의 web: python server.py가 자동 적용됩니다.
   • 포트: 8080 (클라우드타입이 주입하는 PORT 환경변수를 서버가 자동으로 읽습니다.)
3. 환경변수(Secrets) 등록:
   • MOLIT_SERVICE_KEY: 발급받은 실거래가 공용 인증키(Decoding 키) 입력
4. 배포: 배포 완료 후 제공되는 도메인 주소(예: https://port-0-molit-rtms-mcp-xxxxx.cloudtype.app)를 확인합니다.
5. 헬스체크: 웹 브라우저로 서비스 루트 경로(https://[your-domain]/)에 접속하여 ok가 반환되는지 확인합니다. MCP 엔드포인트는 https://[your-domain]/mcp 입니다.

---

🔌 MCP 클라이언트 등록 (Claude Desktop 설정)

claude_desktop_config.json에 다음 중 하나의 방식을 추가하여 프롬프트 상에서 즉시 조회 툴을 사용할 수 있습니다.

1. 원격 배포 방식 (클라우드타입 배포 후 권장)

원격 Streamable HTTP 서버에 연결할 때는 mcp-remote 브리지를 사용합니다. (Node.js 설치 필요)

{
  "mcpServers": {
    "molit-rtms-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://port-0-molit-rtms-mcp-xxxxx.cloudtype.app/mcp"
      ]
    }
  }
}

2. 로컬 Stdio 방식

{
  "mcpServers": {
    "molit-rtms-mcp": {
      "command": "C:\\Users\\10564\\Documents\\LandPrice_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\10564\\Documents\\LandPrice_MCP\\server.py",
        "stdio"
      ],
      "env": {
        "MOLIT_SERVICE_KEY": "your_decoding_service_key_here"
      }
    }
  }
}

설정을 저장한 뒤 Claude Desktop을 완전히 종료 후 재시작해야 커넥터가 인식됩니다.

---

🛠️ 제공하는 툴 명세

1. health_check: API 호출 가용성 및 인증 상태 진단
2. search_land_transactions: 토지 실거래가 조회 및 지목/용도지역 필터 지원
3. search_commercial_transactions: 상업업무용 빌딩/상가 거래 실거래가 조회 및 대지/연면적 이중 평단가 제공
4. search_apartment_transactions: 아파트 실거래가 상세 조회 및 등기일자, 매도/매수 거래주체 확장 필드 스크리닝 제공