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})

Related MCP server: Naver Real Estate MCP

MCP 도구

설치

요구사항

• 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")                  → 학군 정보

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

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

아키텍처

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

엔드포인트 전략

• new.land API 호출 시 429 응답이면 자동으로 m.land로 전환

• 지역 검색 rate limit 시 내장 코드(시도/시군구)로 fallback

• 좌표 기반 검색(search_listings)이 가장 안정적

Rate Limit 방어

응답 필드 설명

매물 (article)

주의사항

• 네이버 부동산의 비공식 API를 사용합니다. API 변경 시 동작하지 않을 수 있습니다.

• 과도한 요청 시 IP 기반 rate limit이 발생할 수 있습니다. (302 → /error/abuse redirect)

• 단시간에 여러 지역을 대량 검색하면 일시적 IP 차단(수 분)이 될 수 있습니다.

• 매물 데이터의 정확성은 네이버 부동산에 등록된 정보에 의존합니다.

• 방 수(roomCnt)는 좌표 기반 검색 API에서 제공되지 않습니다. 면적과 설명으로 추정이 필요합니다.

License

MIT