Skip to main content
Glama
Korea Real Estate MCP

Korea Real Estate MCP

by tae0y

Korea Real Estate MCP

English | 한국어

Connect Claude to Korea's MOLIT real estate API and simulate buy now / buy later / invest only scenarios based on your income, savings, and retirement goals. Provides 14+ tools for live transaction data and financial calculations — apartment, officetel, villa, single-house, and commercial.

Supported Tools

  • Apartment trade / rent (get_apartment_trades, get_apartment_rent)

  • Officetel trade / rent (get_officetel_trades, get_officetel_rent)

  • Villa / multi-family housing trade / rent (get_villa_trades, get_villa_rent)

  • Single-house / multi-household trade / rent (get_single_house_trades, get_single_house_rent)

  • Commercial building trades (get_commercial_trade)

  • Apartment subscription notices / results (get_apt_subscription_info, get_apt_subscription_results)

  • Region code lookup (get_region_code)

Related MCP server: realestate-mcp

Prerequisites

For parsing API specs in hwp or docx format, see Common Utils Guide

Quick Start: Claude Desktop (stdio)

The fastest way to get started — the server runs as a child process of Claude Desktop.

  1. Clone this repository locally.

    git clone <repository_url>
    cd real-estate-mcp
  2. Open the Claude Desktop config file.

    # macOS
    open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
    # Windows
    notepad %APPDATA%\Claude\claude_desktop_config.json
  3. Add the entry below under mcpServers.

    {
      "mcpServers": {
        "real-estate": {
          "command": "uv",
          "args": [
            "run",
            "--directory", "/path/to/real-estate-mcp",
            "python", "src/real_estate/mcp_server/server.py"
          ],
          "env": {
            "DATA_GO_KR_API_KEY": "your_api_key_here"
          }
        }
      }
    }
  4. Restart Claude Desktop. Setup is complete when you can see the real-estate server in the tool list.

  5. For better responses, create a Project in Claude Desktop and paste resources/custom-instructions-ko.md into the Project Instructions tab.

Connect with Other Clients

For other clients, transport options, or per-service API key configuration, see the docs below.

Guide

Transport

Clients

docs/setup-prerequisites.md

—

All clients

docs/setup-with-stdio.md

stdio / local HTTP

Claude Desktop, Claude CLI, Codex CLI

docs/setup-with-http.md

HTTP (remote)

Claude (web), Claude CLI, Codex CLI

docs/setup-reverse-proxy.md

—

Server-side proxy setup (Cloudflare Tunnel)

Contributors

This project exists thanks to all the people who contribute. [Contributing]

Made with contrib.rocks.

Support

If you find this project useful, buy me a coffee!

Available Tools

16 tools
calculate_compound_growthC

Calculate compounded asset growth with initial capital and monthly contributions.

Inputs: years (required), initial_10k (required), annual_rate_pct (required), monthly_contribution_10k (required). Returns: object

calculate_loan_paymentC

Calculate equal principal+interest monthly payment (EMI) in 10k KRW units.

Inputs: years (required), principal_10k (required), annual_rate_pct (required). Returns: object

calculate_monthly_cashflowB

Calculate monthly free cashflow after debt service and costs.

Inputs: monthly_income_10k (required), monthly_living_cost_10k (required), monthly_loan_payment_10k (required), other_monthly_cos… Returns: object

get_apartment_rentA

Return apartment lease and monthly-rent records for a region and month.

Korean keywords: 아파트

Use this alongside get_apartment_trades to compute the jeonse ratio:
  jeonse_ratio = summary.median_deposit_10k / trade summary.median_price_10k
A ratio above 70% signals high gap-investment risk.

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Rent list (unit_name, dong, area_sqm, floor,
           deposit_10k, monthly_rent_10k, contract_type,
           trade_date, build_year)
    summary: median/min/max deposit_10k, monthly_rent_avg_10k,
             jeonse_ratio_pct (null — compute from trade data),
             sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

get_apartment_tradesA

Return apartment sale records and summary statistics for a region and month.

Korean keywords: 아파트

Use summary.median_price_10k as the reference price and
min/max_price_10k to present the price range.

To compute jeonse ratio, call get_apartment_rent for the same region and
month, then divide rent summary.median_deposit_10k by this
summary.median_price_10k.

region_code must be obtained first via the get_region_code tool.

Query strategy:
- For price trend analysis, call this tool for each of the 6 consecutive
  months preceding the current month.
- To check year-over-year changes, also query the same month across
  3 years (e.g. 202412, 202312, 202212).

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Trade list (apt_name, dong, area_sqm, floor,
           price_10k, trade_date, build_year, deal_type)
    summary: median/min/max price_10k, sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

get_apt_subscription_infoA

Return Applyhome (청약홈) APT subscription notice metadata.

Korean keywords: 청약, 분양, 모집공고, 청약 일정, 당첨자 발표, 계약 일정

Use this tool when the user asks:
  - "청약(분양) 공고를 보고 싶어", "이번 달 모집공고 알려줘"
  - "청약 접수 시작/종료일, 당첨자 발표일이 언제야?"
  - "어떤 단지(주택명)가 분양 예정이야?"

This tool returns APT notice metadata such as notice number, house name,
location, schedule dates (announcement, application, winner, contract),
and operator/constructor information. It is not tied to region_code.

Authentication:
  - Set ODCLOUD_API_KEY (Authorization header), or
  - Set ODCLOUD_SERVICE_KEY (serviceKey query parameter).

Args:
    page: Page number (1-based).
    per_page: Items per page.
    return_type: Response type, typically "JSON".

Returns:
    total_count: Total record count from the API.
    items: Notice metadata records.
    page: Current page.
    per_page: Items per page.
    current_count: Number of returned items in this response.
    match_count: Number of matched items (may differ by API).
    error/message: Present on API/network/config failure.

Inputs: page, per_page, return_type. Returns: object

get_apt_subscription_resultsA

Return Applyhome (청약홈) subscription stats: requests, winners, rates, and scores.

Korean keywords: 청약 경쟁률, 청약 신청자, 청약 당첨자, 가점, 가점제

Use this tool when the user asks:
  - "마포구(서울) 청약 경쟁률이 어때?"
  - "청약 신청자/당첨자 통계가 궁금해"
  - "가점 평균/중앙값/최고점은?"

This tool provides aggregated statistics, not individual notice schedules.
For schedules (접수/발표/계약일), use get_apt_subscription_info.

stat_kind choices:
  - "reqst_area": 지역별 청약 신청자 (연령대별 신청건수)
  - "reqst_age":  연령별 청약 신청자 (연령대별 신청건수)
  - "przwner_area": 지역별 청약 당첨자 (연령대별 당첨건수)
  - "przwner_age":  연령별 청약 당첨자 (연령대별 당첨건수)
  - "cmpetrt_area": 지역별 청약 경쟁률 (특별/일반공급 경쟁률)
  - "aps_przwner":  지역별 청약 가점제 당첨자 (가점 통계)

Optional filters use odcloud's cond[...] syntax.

Authentication:
  - Set ODCLOUD_API_KEY (Authorization header), or
  - Set ODCLOUD_SERVICE_KEY (serviceKey query parameter).

Args:
    stat_kind: Which stats endpoint to call (see choices above).
    stat_year_month: Provided year-month in YYYYMM (maps to STAT_DE).
    area_code: Subscription area code (maps to SUBSCRPT_AREA_CODE).
    reside_secd: Residence section code (maps to RESIDE_SECD, used by some endpoints).
    page: Page number (1-based).
    per_page: Items per page.
    return_type: Response type, typically "JSON".

Returns:
    total_count/items/page/per_page/current_count/match_count plus the chosen stat_kind.
    error/message: Present on API/network/config failure.

Inputs: stat_kind (required), page, per_page, area_code, +3 more. Returns: object

get_commercial_tradeA

Return commercial and business building (상업업무용) sale records for a region and month.

Korean keywords: 상업용, 업무용, 상가, 근린생활시설(매매), 상업업무용

Response structure differs from residential tools:
building_type, building_use, land_use, building_ar instead of unit_name/area_sqm.
share_dealing indicates whether the transaction is a partial-share deal.

Use to evaluate commercial real estate investment options alongside residential data.

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Trade list (building_type, building_use, land_use, dong,
           building_ar, floor, price_10k, trade_date, build_year,
           deal_type, share_dealing)
    summary: median/min/max price_10k, sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

get_current_year_monthA

Return the current year and month in YYYYMM format for use with trade/rent tools.

Call this tool when the user asks about current or recent transactions
without specifying a year_month.

Returns:
    year_month: Current year-month string in YYYYMM format (e.g. "202602")

Inputs: no named parameters. Returns: object

get_officetel_rentA

Return officetel lease and monthly-rent records for a region and month.

Korean keywords: 오피스텔

Use alongside get_officetel_trades to compute officetel jeonse ratio
and evaluate rental investment yield.

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Rent list (unit_name, dong, area_sqm, floor,
           deposit_10k, monthly_rent_10k, contract_type,
           trade_date, build_year)
    summary: median/min/max deposit_10k, monthly_rent_avg_10k,
             jeonse_ratio_pct (null), sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

get_officetel_tradesA

Return officetel sale records and summary statistics for a region and month.

Korean keywords: 오피스텔

Use to compare officetel prices against apartment prices in the same area.
Officetel units are typically smaller and cheaper than apartments,
suitable for 1-person households or as rental investment.

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Trade list (unit_name, dong, area_sqm, floor,
           price_10k, trade_date, build_year, deal_type)
    summary: median/min/max price_10k, sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

get_region_codeA

Convert a user-supplied region name to a 5-digit legal district code for the MOLIT API.

Must be called before any trade or rent tool.
Accepts free-form text such as "마포구", "서울 마포구", or "마포구 공덕동".

If multiple matches are returned, show the matches array to the user
and confirm which region they mean before selecting a region_code.

Args:
    query: Free-form region name text supplied by the user.

Returns:
    region_code: 5-digit code for the API parameter (e.g. "11440")
    full_name: Representative legal district name (e.g. "서울특별시 마포구")
    matches: List of all matching results (10-digit original code + name)
    error/message: Present when no match is found

Inputs: query (required). Returns: object

get_single_house_rentA

Return detached and multi-unit house (단독/다가구) lease/rent records for a region and month.

Korean keywords: 단독, 다가구, 단독/다가구, (아파트외 중) 단독/다가구

No unit name is provided. area_sqm is gross floor area (totalFloorAr).
house_type distinguishes "단독" from "다가구".

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Rent list (unit_name="", dong, house_type, area_sqm,
           deposit_10k, monthly_rent_10k, contract_type,
           trade_date, build_year)
    summary: median/min/max deposit_10k, monthly_rent_avg_10k,
             jeonse_ratio_pct (null), sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

get_single_house_tradesA

Return detached and multi-unit house (단독/다가구) sale records for a region and month.

Korean keywords: 단독, 다가구, 단독/다가구, (아파트외 중) 단독/다가구

No unit name is provided by the API. area_sqm is gross floor area (totalFloorAr).
house_type distinguishes "단독" from "다가구".

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Trade list (unit_name="", dong, house_type, area_sqm, floor=0,
           price_10k, trade_date, build_year, deal_type)
    summary: median/min/max price_10k, sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

get_villa_rentA

Return row-house and multi-family (연립다세대) lease/rent records for a region and month.

Korean keywords: 빌라, 연립, 다세대, 연립다세대, (아파트외 중) 저층 공동주택

Use alongside get_villa_trades to compute villa jeonse ratio
and evaluate rental investment yield.

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Rent list (unit_name, dong, house_type, area_sqm, floor,
           deposit_10k, monthly_rent_10k, contract_type,
           trade_date, build_year)
    summary: median/min/max deposit_10k, monthly_rent_avg_10k,
             jeonse_ratio_pct (null), sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

get_villa_tradesA

Return row-house and multi-family (연립다세대) sale records for a region and month.

Korean keywords: 빌라, 연립, 다세대, 연립다세대, (아파트외 중) 저층 공동주택
Notes:
  - "빌라" is not a legal housing type; it is commonly used to refer to "다세대/연립".

Items include house_type ("연립" or "다세대") for distinguishing subtypes.
Villas are typically cheaper than apartments and may suit budget-constrained buyers.

Args:
    region_code: 5-digit legal district code (returned by get_region_code).
    year_month: Target year-month in YYYYMM format (e.g. "202501").
        Call get_current_year_month if not specified by the user.
    num_of_rows: Maximum number of records to return. Default 100.

Returns:
    total_count: Total record count from the API
    items: Trade list (unit_name, dong, house_type, area_sqm, floor,
           price_10k, trade_date, build_year, deal_type)
    summary: median/min/max price_10k, sample_count
    error/message: Present on API error or network failure

Inputs: year_month (required), region_code (required), num_of_rows. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: separate tools for different property types (apartment, officetel, villa, single house, commercial) for trades and rents, plus region code, current year/month, financial calculators, and subscription info. No overlapping functionality.

    Naming Consistency5/5

    Naming follows a consistent pattern: 'get_<property_type>_<action>' for data retrieval (e.g., get_apartment_rent, get_apartment_trades) and 'calculate_<function>' for financial tools. All verbs and property types are uniform.

    Tool Count5/5

    16 tools is well-scoped for a real estate server covering multiple property types, financial analysis, and subscription data. Each tool earns its place without unnecessary redundancy.

    Completeness5/5

    The tool set provides comprehensive coverage: trades and rents for five property types, financial calculators, subscription info/stats, region lookup, and current date. Minimal gaps; only commercial rent is missing but acceptable.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to query and analyze Korean apartment real estate transaction prices (sales and rentals) using natural language, providing tools for price trends, regional comparisons, and rent ratios.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying Korean apartment sales and rental transaction data from the public data portal through natural language, with tools for searching transactions and computing price statistics.
      19 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides South Korean real estate transaction price lookup (sales and rent) for apartments, row houses, single-family homes, and officetels via MCP tools using public data from data.go.kr.
      8
      19 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query Korean apartment real-estate data, including official transaction prices, jeonse ratios, and AI price forecasts for 45,000+ complexes.
      1
      MIT