Provides tools to search and retrieve real estate listings from Naver's real estate platform, including region hierarchy exploration, listing searches by coordinates, complex details, price trends, and school information.
네이버 부동산 매물 조회 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: korea-realestate-mcp
도구 | 설명 |
| 지역 코드 계층 탐색 (시도 → 시군구 → 읍면동) |
| 지역 좌표 + 매물 클러스터 조회 (rate limit에 강건) |
| 특정 동의 단지 목록 |
| 좌표 기반 매물 검색 (가장 안정적) |
| 단지별 매물 목록 (1페이지) |
| 단지별 매물 전체 (자동 페이징) |
| 단지 상세 (세대수, 면적, 입주년도, 건설사 등) |
| 시세 / 실거래가 추이 |
| 주변 학군 (초/중/고) |
Python 3.11+
uv (패키지 매니저)
claude mcp add -s user naver-land -- uv run --directory /path/to/naver-land-mcp python -m servercd naver-land-mcp
uv sync
uv run python -m server1. 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 ← 시도/시군구 코드 및 좌표 데이터엔드포인트 | 용도 | 특징 |
| 지역 검색, 단지 목록 | IP 기반 rate limit 있음 |
| 매물 검색, 좌표 기반 조회 | 상대적으로 안정적 |
new.land API 호출 시 429 응답이면 자동으로 m.land로 전환
지역 검색 rate limit 시 내장 코드(시도/시군구)로 fallback
좌표 기반 검색(search_listings)이 가장 안정적
방어 수단 | 설명 |
Human delay | 요청 간 1~2.5초 랜덤 대기 |
429 retry | 지수 backoff (3^n초) + 랜덤 jitter, 최대 5회 |
Abuse retry | 302 |
Graceful degradation | 모든 retry 소진 시 빈 결과 반환 (크래시 방지) |
필드 | 설명 |
| 보증금 (만원 단위, 숫자. 예: 5000 = 5000만원) |
| 월세 (만원 단위, 숫자. 예: 150 = 150만원) |
| 가격 (한글 표기, 예: "3억 5,000") |
| 부동산 타입 (아파트, 오피스텔, 빌라) |
| 전용면적 (㎡) |
| 공급면적 (㎡) |
| 층 정보 (예: "15/25") |
| 향 (남향, 동향 등) |
| 매물 설명 |
| 네이버 부동산 매물 상세 URL |
네이버 부동산의 비공식 API를 사용합니다. API 변경 시 동작하지 않을 수 있습니다.
과도한 요청 시 IP 기반 rate limit이 발생할 수 있습니다. (302 → /error/abuse redirect)
단시간에 여러 지역을 대량 검색하면 일시적 IP 차단(수 분)이 될 수 있습니다.
매물 데이터의 정확성은 네이버 부동산에 등록된 정보에 의존합니다.
방 수(roomCnt)는 좌표 기반 검색 API에서 제공되지 않습니다. 면적과 설명으로 추정이 필요합니다.
MIT
단지별 매물 전체 (자동 페이징)
Args: complex_no: 단지 코드 trade_type: A1(매매), B1(전세), B2(월세) order: prc_(가격순), spc_(면적순), date_(최신순) max_pages: 최대 페이지 수
Inputs: complex_no (required), trade_type, order, max_pages. Returns: result
단지별 매물 목록 (1페이지)
거래 유형: A1(매매), B1(전세), B2(월세) 정렬: prc_(가격순), spc_(면적순), date_(최신순)
Args: complex_no: 단지 코드 (get_complexes에서 확인) trade_type: 거래 유형 order: 정렬 page: 페이지 번호
Inputs: complex_no (required), trade_type, order, page. Returns: result
단지 상세 정보 (세대수, 면적, 입주년도, 건설사 등)
Args: complex_no: 단지 코드
Inputs: complex_no (required). Returns: result
특정 동의 단지 목록 조회
rate limit 시 좌표 기반 매물 검색으로 자동 전환됩니다. 전환 시 search_listings 사용을 안내합니다.
Args: cortar_no: 읍면동 코드 (10자리) real_estate_type: APT, OPST, VL 등
Inputs: cortar_no (required), real_estate_type. Returns: result
시세/실거래가 추이
Args: complex_no: 단지 코드 area_no: 면적 번호 (get_complex_detail → pyeongNo) trade_type: A1(매매), B1(전세), B2(월세) year: 조회 기간 (기본 5년)
Inputs: complex_no (required), area_no (required), trade_type, year. Returns: result
지역 정보 + 좌표 조회 (m.land 기반, rate limit 강건)
cortarNo를 입력하면 해당 지역의 정확한 좌표, 지역명, 매물 클러스터 수를 반환합니다. search_regions가 rate limit에 걸릴 때 대안으로 사용하세요. 반환된 좌표는 search_listings에서 바로 사용 가능합니다.
Args: cortar_no: 지역 코드 (읍면동 10자리) real_estate_type: APT, OPST, VL 등 trade_type: A1(매매), B1(전세), B2(월세)
Inputs: cortar_no (required), real_estate_type, trade_type. Returns: result
단지 주변 학군 (초/중/고)
Args: complex_no: 단지 코드
Inputs: complex_no (required). Returns: result
좌표 기반 매물 검색 (가장 안정적인 방법)
단지 코드 없이 좌표만으로 해당 지역의 모든 매물을 검색합니다. get_region_info로 좌표를 먼저 확인하거나, 알고 있는 좌표를 직접 입력하세요.
거래 유형: A1(매매), B1(전세), B2(월세) — 여러 개는 콜론으로 구분 (A1:B1:B2) 부동산 타입: APT(아파트), OPST(오피스텔), VL(빌라) — 여러 개는 콜론으로 구분
Args: lat: 위도 (예: 37.3675) lon: 경도 (예: 127.1127) cortar_no: 지역 코드 (선택, 입력 시 더 정확한 결과) real_estate_type: 부동산 타입 (기본: APT) trade_type: 거래 유형 (기본: A1=매매) delta: 검색 반경 (기본: 0.015 ≈ 약 1.5km) max_pages: 최대 페이지 수 (기본: 3, 페이지당 20건)
Inputs: lat (required), lon (required), cortar_no, real_estate_type, +3 more. Returns: result
지역 검색 (시도 → 시군구 → 읍면동 계층 탐색)
지역 코드를 단계적으로 탐색합니다.
기본값(0000000000): 전국 시도 목록
시도 코드: 시군구 목록
시군구 코드: 읍면동 목록
예시: "성남시 분당구 정자동"
search_regions() → 경기도 "4100000000"
search_regions("4100000000") → 성남시분당구 "4113500000"
search_regions("4113500000") → 정자동 "4113510300"
rate limit 시 내장 코드로 자동 fallback됩니다.
Args: cortar_no: 지역 코드 (10자리). 기본값은 전국.
Inputs: cortar_no. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 9 tools
Each tool targets a distinct operation: paginated vs single-page articles, complex details vs list, region info vs hierarchical search, price trends, school info, and coordinate-based search. No two tools overlap in purpose.
All tool names follow a consistent verb_noun pattern with snake_case (get_*, search_*), making the API predictable and easy to navigate.
With 9 tools, the server covers all necessary operations for a real estate data API without being bloated or sparse. Each tool serves a clear role.
The tool set provides comprehensive read-only access to complex info, listings, price history, school info, and region data. Minor gap: no tool for individual listing details beyond the article list, but the overall coverage is strong.
Korean apartment prices, trades, forecasts, tax, school districts, redevelopment, court auctions
Flat-rate US property/parcel search & CSV export for AI agents via MCP.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Korea-native MCP gateway: Korean commerce, payments, messaging, gov & finance APIs for AI agents.
