naver-land-mcp

네이버 부동산 매물 조회 MCP (Model Context Protocol) 서버

네이버 부동산의 비공식 API를 활용하여 현재 매물 정보를 조회합니다.

기능

• 지역 검색 (시도 → 시군구 → 읍면동 계층 탐색)
• 좌표 기반 매물 검색 (아파트, 오피스텔, 빌라)
• 단지별 매물 조회 / 상세 정보
• 시세 및 실거래가 추이
• 주변 학군 정보
• 매매 / 전세 / 월세 거래 유형 지원
• API rate limit 시 자동 엔드포인트 전환 (new.land.naver.com → m.land.naver.com)
• 302 abuse redirect 감지 + 자동 backoff retry
• 요청 간 랜덤 딜레이 (1~2.5초)로 rate limit 방지
• 매물 URL 자동 생성 (https://new.land.naver.com/articles/{articleNo})

MCP 도구

| 도구 | 설명 | |------|------| | search_regions | 지역 코드 계층 탐색 (시도 → 시군구 → 읍면동) | | get_region_info | 지역 좌표 + 매물 클러스터 조회 (rate limit에 강건) | | get_complexes | 특정 동의 단지 목록 | | search_listings | 좌표 기반 매물 검색 (가장 안정적) | | get_articles | 단지별 매물 목록 (1페이지) | | get_all_articles | 단지별 매물 전체 (자동 페이징) | | get_complex_detail | 단지 상세 (세대수, 면적, 입주년도, 건설사 등) | | get_price_info | 시세 / 실거래가 추이 | | get_school_info | 주변 학군 (초/중/고) |

설치

요구사항

• Python 3.11+
• uv (패키지 매니저)

Claude Code에 등록

claude mcp add -s user naver-land -- uv run --directory /path/to/naver-land-mcp python -m server

직접 실행

cd naver-land-mcp
uv sync
uv run python -m server

사용 예시

지역 검색 → 매물 조회 흐름

1. search_regions()                          → 전국 시도 목록
2. search_regions("4100000000")              → 경기도 시군구 목록
3. search_regions("4113500000")              → 분당구 읍면동 목록
4. get_region_info("4113510300")             → 정자동 좌표 확인
5. search_listings(lat=37.38, lon=127.12)    → 주변 매물 검색

단지 상세 조회 흐름

1. get_complexes("4113510300")               → 정자동 단지 목록
2. get_complex_detail("12345")               → 단지 상세 (면적, 세대수)
3. get_all_articles("12345", trade_type="B2") → 월세 매물 전체
4. get_price_info("12345", area_no="1")      → 시세 추이
5. get_school_info("12345")                  → 학군 정보

거래 유형 / 부동산 타입 코드

| 거래 유형 | 코드 | |-----------|------| | 매매 | A1 | | 전세 | B1 | | 월세 | B2 |

| 부동산 타입 | 코드 | |-------------|------| | 아파트 | APT | | 오피스텔 | OPST | | 빌라 | VL | | 아파트분양권 | ABYG | | 재건축 | JGC |

여러 타입 동시 검색: 콜론으로 구분 (예: APT:OPST:VL)

아키텍처

server.py        ← FastMCP 서버, 도구 정의
naver_land.py    ← API 클라이언트 (dual endpoint, retry, fallback)
regions.py       ← 시도/시군구 코드 및 좌표 데이터

엔드포인트 전략

| 엔드포인트 | 용도 | 특징 | |-----------|------|------| | new.land.naver.com | 지역 검색, 단지 목록 | IP 기반 rate limit 있음 | | m.land.naver.com | 매물 검색, 좌표 기반 조회 | 상대적으로 안정적 |

• new.land API 호출 시 429 응답이면 자동으로 m.land로 전환
• 지역 검색 rate limit 시 내장 코드(시도/시군구)로 fallback
• 좌표 기반 검색(search_listings)이 가장 안정적

Rate Limit 방어

| 방어 수단 | 설명 | |-----------|------| | Human delay | 요청 간 1~2.5초 랜덤 대기 | | 429 retry | 지수 backoff (3^n초) + 랜덤 jitter, 최대 5회 | | Abuse retry | 302 /error/abuse 감지 시 10초×attempt backoff, 최대 5회 | | Graceful degradation | 모든 retry 소진 시 빈 결과 반환 (크래시 방지) |

응답 필드 설명

매물 (article)

| 필드 | 설명 | |------|------| | deposit | 보증금 (만원 단위, 숫자. 예: 5000 = 5000만원) | | rent | 월세 (만원 단위, 숫자. 예: 150 = 150만원) | | price | 가격 (한글 표기, 예: "3억 5,000") | | realEstateType | 부동산 타입 (아파트, 오피스텔, 빌라) | | exclusiveArea | 전용면적 (㎡) | | supplyArea | 공급면적 (㎡) | | floorInfo | 층 정보 (예: "15/25") | | direction | 향 (남향, 동향 등) | | featureDesc | 매물 설명 | | url | 네이버 부동산 매물 상세 URL |

주의사항

• 네이버 부동산의 비공식 API를 사용합니다. API 변경 시 동작하지 않을 수 있습니다.
• 과도한 요청 시 IP 기반 rate limit이 발생할 수 있습니다. (302 → /error/abuse redirect)
• 단시간에 여러 지역을 대량 검색하면 일시적 IP 차단(수 분)이 될 수 있습니다.
• 매물 데이터의 정확성은 네이버 부동산에 등록된 정보에 의존합니다.
• 방 수(roomCnt)는 좌표 기반 검색 API에서 제공되지 않습니다. 면적과 설명으로 추정이 필요합니다.

License

MIT