realestate-mcp

국토교통부 실거래가 공공데이터(data.go.kr)를 MCP 도구로 제공하는 서버입니다. 아파트/연립다세대/단독다가구/오피스텔의 매매·전월세 실거래가를 지역코드+계약년월로 조회합니다.

제공 도구 (8개)

도구명	설명
get_apt_trade	아파트 매매 실거래가
get_apt_rent	아파트 전월세 실거래가
get_sh_trade	단독/다가구 매매 실거래가
get_sh_rent	단독/다가구 전월세 실거래가
get_rh_trade	연립다세대 매매 실거래가
get_rh_rent	연립다세대 전월세 실거래가
get_offi_trade	오피스텔 매매 실거래가
get_offi_rent	오피스텔 전월세 실거래가

공통 입력: regionCode(법정동 앞 5자리, 예: 서울 종로구 11110), dealYearMonth(YYYYMM), pageNo(선택), numOfRows(선택, 기본 10)

배포

Fly.io에 HTTP(streamable) MCP 서버로 배포되어 있습니다: https://realestate-mcp-hlucent.fly.dev/mcp

serviceKey는 서버에 저장하지 않고, 요청마다 ?key= 쿼리 파라미터로 본인의 data.go.kr 인증키를 전달합니다 (seoul-air-quality-mcp, construction-alert-mcp와 동일한 방식).

https://realestate-mcp-hlucent.fly.dev/mcp?key=본인의_data.go.kr_인증키

키 발급: https://www.data.go.kr → 회원가입 → 국토교통부_실거래가 자료 API별 활용신청 → 인증키 확인

로컬 개발

npm install
cp .env.example .env   # DATA_GO_KR_SERVICE_KEY 입력 (통합 테스트 스크립트용)
npm run dev             # http://localhost:8080/mcp

MCP 클라이언트 설정 시에도 배포와 동일하게 URL의 ?key=로 인증키를 전달합니다 (서버 프로세스 환경변수로는 주입하지 않음).

문서

• 아키텍처/설계: docs/ARCHITECTURE.md
• API별 상세 스펙 요약: docs/api-spec/
• 개발일지(자동 생성): docs/devlog/

개발 참고

Claude Code로 작업 시 CLAUDE.md를 먼저 읽으세요. 토큰 절약을 위한 작업 규칙이 정리되어 있습니다.