Tw Lvr

PyPI version Python PyPI downloads License: MIT MCP CI GitHub stars GitHub issues GitHub last commit

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

Tool	Description
query_real_price_tool	Query real estate transactions by city, district, road, building, date range, and transaction type

query_type options:

Value	Description
biz	買賣（sales transactions）
rent	租賃（rental transactions）
presale	預售屋（pre-sale housing）
saleremark	預售屋建案（pre-sale project listings）

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

---

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