korea-realestate-mcp 0.1.0

Korean real estate MCP server - apartment transaction data lookup & analysis for AI agents

korea-realestate-mcp

한국 부동산(아파트) 실거래가 조회 및 분석을 위한 MCP(Model Context Protocol) 서버입니다.

AI 에이전트(Claude Desktop, Cursor, Claude Code 등)에서 자연어로 아파트 매매/전월세 시세를 조회하고 분석할 수 있습니다.

한국 부동산 데이터를 제공하는 최초의 MCP 서버입니다.

제공 도구

도구	설명
realestate_search_apt_trade	아파트 매매 실거래가 조회
realestate_search_apt_rent	아파트 전월세 실거래가 조회
realestate_get_region_code	지역명 → 법정동 코드 조회 (퍼지 매칭)
realestate_analyze_price_trend	시세 추이 분석 (월별 통계, 변동률)
realestate_compare_regions	2~5개 지역 시세 비교
realestate_analyze_rent_ratio	매매가 대비 전세가율 분석
realestate_get_apt_summary	특정 아파트 단지 종합 요약

설치

uvx (권장)

uvx korea-realestate-mcp

pip

pip install korea-realestate-mcp

설정

1. API 키 발급

공공데이터포털에서 회원가입 후 아래 API의 활용 신청을 합니다:

• 국토교통부_아파트매매 실거래자료 (링크)
• 국토교통부_아파트 전월세 자료 (링크)

신청 즉시 승인되며, 마이페이지에서 **서비스 키(Decoding)**를 복사합니다.

2. Claude Desktop 설정

claude_desktop_config.json에 아래를 추가합니다:

{
  "mcpServers": {
    "korea-realestate": {
      "command": "uvx",
      "args": ["korea-realestate-mcp"],
      "env": {
        "PUBLIC_DATA_API_KEY": "<발급받은 서비스 키>"
      }
    }
  }
}

3. Claude Code 설정

export PUBLIC_DATA_API_KEY="<발급받은 서비스 키>"
claude mcp add korea-realestate -- uvx korea-realestate-mcp

사용 시나리오

1. 아파트 시세 조회

"강남구 아파트 최근 시세 알려줘"

realestate_search_apt_trade가 호출되어 최근 거래 내역을 Markdown 테이블로 반환합니다.

2. 특정 단지 시세 추이

"래미안대치팰리스 84㎡ 최근 1년 시세 추이 보여줘"

realestate_analyze_price_trend가 월별 평균가, 변동률, 거래량을 분석합니다.

3. 지역 비교

"분당 vs 일산 아파트 가격 비교해줘"

realestate_compare_regions가 지역별 평균가, 중앙값, ㎡당 단가를 비교합니다.

4. 전세가율 분석

"분당 전세가율 어때?"

realestate_analyze_rent_ratio가 매매가 대비 전세가율과 갭투자 금액을 산출합니다.

5. 단지 종합 정보

"판교 힐스테이트 종합 정보"

realestate_get_apt_summary가 최근 거래, 면적대별 시세, 전세가율을 요약합니다.

데이터 출처

• 국토교통부 실거래가 공개시스템
• 공공데이터포털 API

기술 스택

• Python 3.10+
• FastMCP (MCP Python SDK)
• httpx (비동기 HTTP)
• SQLite 캐시 (aiosqlite)
• pandas (데이터 분석)

라이선스

MIT