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.

Related MCP server: taiwan-data-hub

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 筆： ...

Installation

From PyPI (recommended)

# Install as a uv-managed tool
uv tool install mcp-tw-lvr

# One-time: install the Chromium browser Playwright drives
uvx --from mcp-tw-lvr playwright install chromium

# Run the MCP server
uv tool run mcp-tw-lvr

Or with pipx:

pipx install mcp-tw-lvr
pipx run --spec mcp-tw-lvr playwright install chromium
mcp-tw-lvr

From source (contributors)

git clone https://github.com/asgard-ai-platform/mcp-tw-lvr.git
cd mcp-tw-lvr
uv sync
uv run playwright install chromium
uv run mcp-tw-lvr

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

Claude Code / MCP client integration

After installing from PyPI, add to your MCP client config (e.g. ~/.claude.json or a project-local .mcp.json):

{
  "mcpServers": {
    "mcp-tw-lvr": {
      "command": "uvx",
      "args": ["mcp-tw-lvr"]
    }
  }
}

Running from a local clone? Use the in-repo .mcp.json shape instead:

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

# Fast unit-only run (no network)
uv run pytest -m "not e2e"

# Live E2E tests against the real portal (~30-60s each)
uv run pytest -m e2e -v

See CONTRIBUTING.md for the full dev workflow.

License

MIT License