# real-estate-mcp: fourteen Korean property data tools behind one API key

> The repository wraps South Korea's public transaction and subscription data in an MCP server, but each property type and each document format carries its own service registration. Last pushed 2026-07-18, one release at 0.1.0.

**tae0y/real-estate-mcp** — Ask Claude about Korean apartment prices, powered by the Ministry of Land, Infrastructure and Transport's open API.

- Repository: https://github.com/tae0y/real-estate-mcp
- Stars: 378 · Forks: 64
- Language: Python
- License: MIT
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/tae0y-real-estate-mcp

## The tool list is organised by Korean property type, not by question

The server exposes fourteen or more tools, and the naming follows the categories the Korean government actually publishes rather than anything a buyer would ask. Apartment transactions and rents come as `get_apartment_trades` and `get_apartment_rent`. Officetel, the small mixed office and studio unit type, has its own pair. Villas and multi-family housing, which the data calls 연립다세대, have another pair. Detached houses and multi-household properties, 단독/다가구, have two more. Commercial and business buildings expose only a trade call, `get_commercial_trade`, with no rent counterpart. Two tools cover the apartment subscription system that ordinary buyers compete for: `get_apt_subscription_info` for notices and `get_apt_subscription_results` for results. The last tool, `get_region_code`, is the lookup you need before any of the others will return anything, since every query is addressed by region code rather than by name.

The gap between that list and a natural question is deliberate. The stated goal is a server that can simulate buy now, buy later, and invest only decisions against income, savings, and retirement goals, so the transaction and rent calls are meant to be combined by the client rather than returned as a finished recommendation. The property categories are the ones MOLIT publishes. Anything outside South Korea is out of scope by construction.

## Eleven service registrations, not one key

The single largest cost of running this server is registration paperwork. The prerequisite list names eleven separate services on the public data portal, and each has its own application. Apartment sale and lease prices are two. Officetel sale reports and lease data are two more. The villa and multi-family sale and lease datasets are two. Detached and multi-household sale and lease data are two. Commercial building sale reports are one. The subscription data set, the file download of subscription information, and the subscription applicant and winner lookup service are the last three. An account on the portal is not enough; each service issues its own key, and a client that only holds the first key will find most tools returning nothing.

The configuration file makes this explicit rather than hiding it. A single variable carries the main key:

```bash
# Public Data Portal API key (data.go.kr)
# Obtain from https://www.data.go.kr and paste below
DATA_GO_KR_API_KEY=your_api_key_here
```

Two of the downstream services reuse that key by default, which is the one shortcut in the whole chain. The odcloud Applyhome subscription backend and the Onbid next-generation service, identified as B010003, both fall back to DATA_GO_KR_API_KEY unless you set their own variables. Everything else needs a separate portal application, so a working deployment usually means a dashboard with a dozen rows on it rather than one credential.

## The server runs as a uv child process of the desktop client

Setup for Claude Desktop assumes you clone the project and let the client launch it. The clone is the first step:

```bash
git clone <repository_url>
cd real-estate-mcp
```

The config file lives in a platform specific location, opened with a shell command on macOS and with notepad on Windows:

```bash
# macOS
open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
```

The entry you add under `mcpServers` points at a single file inside the checkout and passes the directory explicitly, which is what lets uv resolve the project environment without a separate activation step:

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

Two things follow from that shape. The key is written into a JSON file in plain text, on a path that sits inside the user's application support directory. And the working directory is hardcoded as an absolute path, so moving the checkout breaks the server until the file is edited. Restart the client afterwards, and the setup is finished when `real-estate` appears in the tool list. The same repository also exposes a console entry point named `real-estate-mcp`, so the server can be started without a client at all.

## Four transports, and only two clients appear in more than one

The desktop path is one of several documented arrangements, and the difference matters if your client is not Claude Desktop. A local stdio setup or a local HTTP server covers Claude Desktop, Claude CLI, and Codex CLI. A remote HTTP deployment covers the web version of Claude as well as the two command line clients, which is the only reason to choose it, since a browser client cannot spawn a child process. A fourth guide covers server side proxying through a Cloudflare Tunnel, which is the documented path for exposing the server without opening a port.

The remote route pulls in a credential the local route never needs. The environment file marks the tunnel token as required for Docker and Cloudflare Tunnel deployment and points at a separate setup document for it:

```bash
# Cloudflare Tunnel token (required for Docker/Cloudflare Tunnel deployment).
# Obtain from Cloudflare Zero Trust → Networks → Tunnels → your tunnel → token.
# See docs/setup-cloudflare.md for setup instructions.
# CLOUDFLARE_TUNNEL_TOKEN=your_tunnel_token_here
```

Note what the local guides do not carry. There is no authentication layer described for the remote HTTP transport, so a tunnel that forwards traffic to this server forwards it to anyone who has the address. The repository does include a `docker/` directory, but the Docker path is tied to the tunnel setup rather than offered as a standalone local container.

## Coverage has a floor of 80 percent and two directories sit outside it

The test configuration is stricter than most small Python projects and says something about how the author intends to work. Pytest is pointed at the tests directory, asyncio runs in automatic mode, and coverage is enforced as a build failure rather than a report:

```bash
[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
addopts = "--cov=src/real_estate --cov-report=term-missing --cov-fail-under=80"
```

Branch coverage is on, and two paths are omitted from the measurement entirely. The coverage run lists `src/real_estate/ui/*` and `src/real_estate/common_utils/hwp_parser.py` in its omit list, and the entry for the second continues past the point where the captured file was cut off. The practical reading is that the interface layer and the Korean word processing parser are the two parts not held to the same standard, which is consistent with the rest of the repository treating document parsing as a separate concern with its own guide.

Around that sit the usual guard rails. Bandit runs in the standard configuration with tests and scripts excluded and the assert warning skipped, pyright operates in standard type checking mode against a local .venv, and ruff enforces a hundred character line length against Python 3.12 with the E, F, I, N, and W rule sets selected and no ignores.

## The dependency list names the document formats the portal still ships

The runtime dependencies are short and each one points at a specific obstacle. uvicorn and httpx cover the remote transport and the async calls to the portal. pydantic-settings handles configuration. python-dotenv reads the environment file that holds the keys. The MCP package brings its own command line interface. The interesting three are defusedxml, olefile, and pillow, and they have nothing to do with property data. They exist because Korean public agencies still publish API specifications as hwp and docx documents, which are container formats wrapping binary or XML payloads. Parsing them safely needs an XML parser hardened against entity expansion, a reader for the OLE compound structure, and an image library for whatever a specification turns out to embed.

There is a separate guide for that work, referenced from the prerequisite section and pointed at a common utils document, which is the clearest signal in the repository about where the difficulty sits. The data retrieval is a solved problem, since it is just an authenticated HTTP call. Turning agency documentation into parseable structure is not, and the coverage exclusion for the hwp parser confirms that it is also the least finished part of the code.

The package metadata is correspondingly plain. The distribution is named `real_estate` at version 0.1.0, requires Python 3.12 or newer, builds through uv, and opts into prerelease resolution. The repository keeps a Korean README alongside the English one, a CLAUDE.md, a .mcp.json, a pre-commit configuration, a pinned .python-version, and a uv lockfile, so the Python environment is reproducible even though the runtime environment is not.

## A 0.1.0 release from a single day of work

The version history has one entry. v0.1.0 was published on 2026-07-18, and the last push to the repository carries the same date. Everything in this article reflects that snapshot, which matters more here than in most projects because the value of the server is the coverage of the tool surface, and the tool surface is exactly the sort of thing that grows when someone registers another portal service.

What the repository does not contain is a changelog, a roadmap, or a stated compatibility range for the portal itself. It also does not explain what happens when the portal changes a response schema, which is the most common way a data wrapper like this breaks without anyone touching the code. If you depend on it, the pin is a real constraint rather than a formality, and you should expect to re-check the tool list after each new release rather than assuming the fourteen tools will still be there.

The support and funding surface is minimal, a single contributor credit page and a small donation link, so there is no obvious escalation path when a service key stops working.

## Conclusion

This suits an English-speaking developer who needs actual Korean transaction records and accepts reading them through an English interface, and who can spend an afternoon registering services on the public data portal. It is a poor fit for anyone who needs Zillow, MLS, or US property data, since the whole surface is Korea specific. Before starting, check three things: that you can obtain each service key separately rather than one generic key, that Python 3.12 or newer is available because the package requires it, and that the hwp and docx parsing path documented separately is the one your question needs. The project was last pushed on 2026-07-18 and sits at version 0.1.0, so treat the tool list as a snapshot rather than a settled API.

## FAQ

### What does real-estate-mcp do for Korean property data?

It connects an MCP client to South Korea's MOLIT real estate API. The tools cover apartment, officetel, villa, single house, and commercial property, returning both transaction prices and rent figures from the public data portal.

### How many API keys does real-estate-mcp need from data.go.kr?

The prerequisite list names eleven separate services on the public data portal, each issued separately. The odcloud Applyhome and Onbid services reuse the main DATA_GO_KR_API_KEY by default, but the transaction and lease datasets need their own registrations.

### Can I run real-estate-mcp without Claude Desktop?

Yes. The setup guides cover a local stdio or HTTP server for Claude Desktop, Claude CLI, and Codex CLI, plus a remote HTTP transport that also works with Claude on the web. A separate guide covers proxying the server through a Cloudflare Tunnel.

### Which tools in real-estate-mcp return subscription data?

Two tools cover the apartment subscription system: `get_apt_subscription_info` for notices and `get_apt_subscription_results` for results. Subscription data comes from Korea Real Estate Institute services rather than from the MOLIT transaction endpoints.

### What does real-estate-mcp need before Claude can answer questions about a Korean apartment?

A region code. The `get_region_code` lookup has to run before the transaction and rent tools will return anything for a given area, since those calls are addressed by region code rather than by a place name.

## Sources

- [Issues](https://github.com/tae0y/real-estate-mcp/issues)
- [License: MIT](https://github.com/tae0y/real-estate-mcp/blob/main/LICENSE)
- [README](https://github.com/tae0y/real-estate-mcp/blob/main/README.md)
- [Releases](https://github.com/tae0y/real-estate-mcp/releases)
- [tae0y/real-estate-mcp on GitHub](https://github.com/tae0y/real-estate-mcp)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tae0y-real-estate-mcp