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.

[!WARNING]
Deprecation Notice — effective June 1, 2025

Caddy reverse proxy support will be removed. Cloudflare Tunnel is the recommended replacement and is already available in docker/docker-compose.yml via --profile cloudflare. See docs/setup-reverse-proxy.md for migration instructions.

Onbid (공매) support will be removed. Onbid's API has required repeated patches that are no longer sustainable to maintain as a personal project. All get_public_auction_* and get_onbid_* tools will be deleted.

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)
Onbid public auction bid results (get_public_auction_items, get_public_auction_item_detail) / 🗑️ Removed June 1, 2025
Onbid item lookup (get_onbid_thing_info_list) / 🗑️ Removed June 1, 2025
Onbid code / address lookup (get_onbid_*_code_info, get_onbid_addr*_info) / 🗑️ Removed June 1, 2025
Region code lookup (get_region_code)

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.

Clone this repository locally.

git clone <repository_url>
cd real-estate-mcp

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

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

Restart Claude Desktop.
Setup is complete when you can see the real-estate server 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
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 / Caddy)

Deprecation notice (April 2025): ChatGPT support and the Caddy reverse proxy option will be removed at the end of April 2025.
ChatGPT's required OAuth flow (Auth0 + PKCE + DCR) is too complex to maintain — it will be re-evaluated for a future release.
Caddy is replaced by Cloudflare Tunnel, which requires no port forwarding and no TLS certificate management.

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!