real-estate-mcp: Korean Apartment Transaction Data Inside Claude

What tae0y/real-estate-mcp actually connects

Korea's Ministry of Land, Infrastructure and Transport publishes apartment, officetel, villa, single-house and commercial transaction records through the public data portal at data.go.kr. Those records are authoritative but awkward: they arrive as XML or JSON from a dozen separate endpoints, each with its own request shape, and the portal's own interface is not built for exploratory questions. This project wraps those endpoints as Model Context Protocol tools so a Claude client can call them directly during a conversation.

The intended user is someone reasoning about a Korean property decision in natural language, not someone building a valuation pipeline. The README frames the goal as simulating buy now, buy later, or invest only scenarios against your income, savings and retirement goals. So the tool set is split between retrieval (trade and rent lookups by property type) and calculation, and the value comes from the model being able to pull a real transaction history and then run the arithmetic on it in one turn.

It is not a general real estate MCP server. Everything is scoped to Korean administrative regions and Korean property categories, and the underlying data is transaction reports filed with the government, which means the coverage and the lag are whatever MOLIT publishes.

The tool surface and how a query flows

The README lists the supported tools explicitly. Retrieval tools come in pairs by property type: get_apartment_trades and get_apartment_rent, get_officetel_trades and get_officetel_rent, get_villa_trades and get_villa_rent, get_single_house_trades and get_single_house_rent, plus get_commercial_trade for commercial buildings. Subscription data is separate: get_apt_subscription_info and get_apt_subscription_results cover 청약 notices and results. get_region_code is the lookup that turns a place name into the code the other tools expect.

The data flow is a child process, not a service you query. Under stdio transport the MCP server runs as a process spawned by Claude Desktop, receives tool calls over standard input and output, and for each call issues an async HTTP request through httpx to the relevant data.go.kr endpoint. The API key travels in the environment of that child process. Results come back as tool output to the model, which then reasons over them.

That design has a consequence worth naming: there is no local database. Every question hits the upstream API, so latency and rate limits belong to data.go.kr, not to this project. The repository does include a docker directory and the .env.example mentions a Cloudflare Tunnel token for Docker deployment, and the docs table lists an HTTP transport guide plus a reverse proxy guide, so a remote HTTP mode exists for clients that cannot spawn processes. The README does not describe caching behaviour for either transport.

Installing it and getting a first answer out of Claude

The prerequisites are uv and an API key. The key is not one key for everything: the README links eleven separate data.go.kr services you must apply for individually, covering apartment trade and rent, officetel trade and rent, villa trade and rent, single-house trade and rent, commercial trade, and the two 청약홈 subscription services. The environment variable that carries the key is DATA_GO_KR_API_KEY, and .env.example shows that the 청약홈 odcloud endpoints and the Onbid service reuse it by default, with ODCLOUD_API_KEY, ODCLOUD_SERVICE_KEY and ONBID_API_KEY as optional overrides.

Start by cloning the repository and confirming the interpreter. The project declares requires-python >=3.12 and builds with uv_build.

git clone <repository_url>
cd real-estate-mcp
uv run python -c "import sys; print(sys.version)"

You should see a 3.12 or newer version string. If uv resolves an older interpreter, the package will not install.

Next, register the server with Claude Desktop. The README's quick start opens the config file for you on macOS, and on Windows it points at %APPDATA%\Claude\claude_desktop_config.json. Add the entry under mcpServers, replacing the directory and the key.

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

After restarting Claude Desktop, the README says setup is complete when the real-estate server appears in the tool list. A first real use is a region lookup followed by a trade query: ask Claude for the region code for the district you care about, then ask for recent apartment trades there. The README also recommends creating a Project in Claude Desktop and pasting resources/custom-instructions-ko.md into the Project Instructions tab, which is where the scenario framing for buy now versus buy later lives. Note that the filename ends in -ko, so those instructions are Korean.

If you are not on Claude Desktop, the docs table points to docs/setup-with-stdio.md for Claude CLI and Codex CLI, docs/setup-with-http.md for remote HTTP clients, and docs/setup-reverse-proxy.md for a Cloudflare Tunnel deployment.

Where it breaks: keys, coverage and the stdio assumption

The most immediate failure mode is key scope. A data.go.kr key that is approved for apartment trades will not necessarily be approved for officetel rent or for the 청약홈 services, because each is a separate application. The project surfaces this as an upstream error, not as a friendly message, and the README does not document per-tool error handling for missing approvals. Budget time for the portal's approval process before you evaluate anything else.

The second limitation is coverage by design. If you need US listings, MLS data, or anything outside Korea's MOLIT reporting, this is simply the wrong tool; the tool names and the region code lookup are built around Korean administrative divisions. Even inside Korea, the data is transaction reports, so it reflects what was filed, not what is currently listed for sale.

The third is deployment friction. The quick start assumes a local clone and a child process, which is fine on a laptop and awkward on anything shared. The repository offers an HTTP transport and a Docker path, but .env.example marks CLOUDFLARE_TUNNEL_TOKEN as required for the Docker and Cloudflare Tunnel deployment, and points at docs/setup-cloudflare.md for the token. That is real infrastructure to run. Finally, the README does not document rollback, version pinning for the upstream APIs, or what happens when MOLIT changes a response schema, so the upgrade path is not described.

How it differs from a listings-oriented MCP server

The obvious comparison is a listings server such as a Zillow or MLS MCP integration. The approaches differ at the data layer, not just the geography. Listing-oriented servers read from commercial platforms whose records describe properties currently or recently on the market, with asking prices, photos and agent contact details. This project reads government-filed transaction reports: what actually changed hands, at what reported price, on what date, plus 청약 subscription outcomes.

That difference decides your use case. For "what is this neighbourhood asking," a listings server is the right shape. For "what did three-bedroom apartments in this district actually sell for over the last year, and can I afford one given my savings," the transaction record is the better source, and it is the source this project exposes. It is also why the tool set includes rent lookups alongside trade lookups: 전월세 data is the rental half of the same reporting system.

The trade-off is freshness and richness. Transaction reports lag the market and carry no listing narrative. If your questions are about what is on offer rather than what closed, this project will not answer them.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-07-18, which is recent enough that the codebase is still moving. The only release is v0.1.0, published the same day, so there is no track record of upgrade migrations to learn from. Treat the tool names as stable for now and the internals as unsettled.

Licensing is MIT, which is permissive and imposes no conditions on how you use the code beyond keeping the notice. That says nothing about the data: the MOLIT records come from data.go.kr under that portal's own terms, and the README points you there to apply. MIT on the server code does not grant you any rights to the transaction data, and the README does not spell out the portal's usage conditions, so read them at the source. This is not legal advice.

The practical upgrade cost sits in three places. Python version: the project requires 3.12 or newer, so an environment on 3.11 will not run it. Dependency drift: the pinned ranges include mcp[cli]>=1.0.0, httpx>=0.28.0 and pydantic-settings>=2.0.0, and MCP itself is a young protocol, so a client-side change can affect the server. Key management: the optional overrides in .env.example mean a deployment can carry three different credentials, and nothing in the README describes rotating them. The dev toolchain is unusually complete for a v0.1.0, with pytest, respx, ruff, pyright, bandit and pip-audit configured, and the pytest settings enforce coverage of at least 80 percent with --cov-fail-under=80, which is a reasonable signal that the author intends the test suite to keep pace with changes.

Editorial conclusion

Adopt it if you are working with Korean housing transaction data and already use an MCP-capable client, because the tool set covers apartment, officetel, villa, single-house and commercial trades plus subscription notices, and the repository ships Korean project instructions for better answers. Do not adopt it if you need US MLS or Zillow listings, or if you want a hosted service, since every deployment path here assumes you hold the data.go.kr keys. Verify first that your data.go.kr account has been approved for each specific service you need, that your Python environment is 3.12 or newer, and that the region codes you plan to query resolve through get_region_code before you build anything on top of the results.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tae0y/real-estate-mcp on GitHub