# mcp-tw-lvr

[![PyPI version](https://img.shields.io/pypi/v/mcp-tw-lvr)](https://pypi.org/project/mcp-tw-lvr/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-tw-lvr)](https://pypi.org/project/mcp-tw-lvr/)
[![PyPI downloads](https://img.shields.io/pypi/dm/mcp-tw-lvr)](https://pypi.org/project/mcp-tw-lvr/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)
[![CI](https://img.shields.io/github/actions/workflow/status/asgard-ai-platform/mcp-tw-lvr/publish.yml?label=publish)](https://github.com/asgard-ai-platform/mcp-tw-lvr/actions/workflows/publish.yml)
[![GitHub stars](https://img.shields.io/github/stars/asgard-ai-platform/mcp-tw-lvr)](https://github.com/asgard-ai-platform/mcp-tw-lvr/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/asgard-ai-platform/mcp-tw-lvr)](https://github.com/asgard-ai-platform/mcp-tw-lvr/issues)
[![GitHub last commit](https://img.shields.io/github/last-commit/asgard-ai-platform/mcp-tw-lvr)](https://github.com/asgard-ai-platform/mcp-tw-lvr/commits/main)

MCP server for querying Taiwan's 實價登錄 (real estate transaction registry) via web scraping of [lvr.land.moi.gov.tw](https://lvr.land.moi.gov.tw). Built on [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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`](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)

```bash
# 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`:

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

### From source (contributors)

```bash
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`):

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

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

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

```bash
# 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](CONTRIBUTING.md) for the full dev workflow.

## License

MIT License