Korea Real Estate MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Korea Real Estate MCP show me apartment trades in Gangnam-gu for June 2024"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Korea Real Estate MCP
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
API key from 공공데이터포털 — apply for the services below:
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.
Clone this repository locally.
git clone <repository_url> cd real-estate-mcpOpen the Claude Desktop config file.
# macOS open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"# Windows notepad %APPDATA%\Claude\claude_desktop_config.jsonAdd 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" } } } }Restart Claude Desktop. Setup is complete when you can see the
real-estateserver in the tool list.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 |
— | All clients | |
stdio / local HTTP | Claude Desktop, Claude CLI, Codex CLI | |
HTTP (remote) | Claude (web), Claude CLI, Codex CLI | |
— | 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 toolscalculate_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
Scored across 16 tools
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 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.
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.
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
Related MCP Connectors
Korean apartment data: official transaction prices, jeonse ratios, AI forecasts. 45,000+ complexes.
Korean real estate: court auctions, 10M+ MOLIT records, subscription notice facts, loan/DSR rules
Official Korean apartment sale prices (MOLIT). Clean JSON, data global models cannot know — paid pe…
All KR Data tools in one server: Korean business checks, addresses, laws, car flood records & more
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.7MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT
- AlicenseAqualityDmaintenanceProvides 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.819 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to query Korean apartment real-estate data, including official transaction prices, jeonse ratios, and AI price forecasts for 45,000+ complexes.1MIT