mcp-tw-lvr

MCP server for querying Taiwan's 實價登錄 (real estate transaction registry) via web scraping of lvr.land.moi.gov.tw. Built on Model Context Protocol (MCP) over stdio JSON-RPC 2.0.

Note: This tool automates the government's official web portal using Playwright. Each query takes ~15–20 seconds and loads the live site — use sparingly.

Available Tools

query_type options:

Year defaults: If start_year / end_year are omitted, they default to "last year through this year" computed at call time in the ROC calendar (民國 = CE − 1911), so the tool never becomes stale.

Response shape: By default the tool returns dicts with friendly English keys (address, total_price, unit_price, building_name, layout, transaction_date, latitude, longitude, …). Field set differs by query_type — see src/lvr/adapter.py for the complete mappings. Pass raw=True to receive the government API's original single-letter keys (a, tp, p, …) instead.

Usage Examples

查詢高雄市買賣行情

你： 我想知道高雄市鹽埕區今年的房屋售價

AI 呼叫：

query_real_price_tool(
  city = "高雄市",
  town = "鹽埕區",
  query_type = "biz",
  start_year = 115,
  start_month = 1,
  end_year = 115,
  end_month = 12,
)

結果： 以下是 高雄市鹽埕區 115 年（1–3 月）買賣實價登錄統計，共 21 筆，其中 10 筆為特殊關係交易（親友、含租約等），以下以 一般正常交易 11 筆為主分析： ...

查詢台北市租金行情

你： 台北市信義區今年的租賃行情怎麼樣？

AI 呼叫：

query_real_price_tool(
  city = "台北市",
  town = "信義區",
  query_type = "rent",
  start_year = 114,
  start_month = 1,
  end_year = 114,
  end_month = 12,
)

結果： 以下是 台北市信義區 115 年（1–2 月）整戶住宅租賃行情，有效筆數 80 筆： ...

Quick Start

# Install dependencies
uv sync
uv run playwright install chromium

# Run server
uv run mcp-tw-lvr

# Interactive dev/test (MCP Inspector)
uv run mcp dev src/lvr/server.py

Claude Code Integration

.mcp.json is included. To use in another project, add to your config:

{
  "mcpServers": {
    "mcp-tw-lvr": {
      "command": "uv",
      "args": ["run", "mcp-tw-lvr"],
      "cwd": "/path/to/mcp-tw-lvr"
    }
  }
}

Data Source

All data is scraped from https://lvr.land.moi.gov.tw — Taiwan Ministry of the Interior's official real estate transaction registry. No API key required, but each query drives a real browser session against the live site.

Testing

# E2E tests against the live site (~1 min)
uv run python tests/test_all_tools.py

License

MIT License