Ziroom MCP

This is a Ziroom rental MCP service: it supports both stateful listing filtering and session-free scraping of a single detail-page URL. When searching, the Agent makes consecutive tool calls within the same session_id, while the server keeps the browser page, filter state, version number, and rollback checkpoints.

Tools

• create_search_session: Opens the corresponding Ziroom page for a city.

• get_filter_schema: Reads the current fields, options, control types, and selected state.

• search_location: Searches for a residential community, business district, or metro station.

• select_filter_option: Selects a single-choice or multi-choice tag.

• set_filter_range: Sets the rent range.

• set_sort: Sets sorting by price, area, etc.

• get_results: Returns listing names, URLs, all current conditions, and verification results.

• get_listing_detail: Returns structured details and a Chinese Markdown report via a /x/{listing-id}.html URL.

• restore_checkpoint: Restores the complete state from before an operation.

• reset_filter: Resets a specified field entirely to its default value.

• close_search_session: Closes the page and releases resources.

Installation

cd C:\path\to\ziroom-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[test]"

The service gives priority to Chrome or Edge already installed on Windows. If no browser is available, it installs Playwright Chromium:

.venv\Scripts\python.exe -m playwright install chromium

Detail scraping and search share the same Playwright browser process. Each get_listing_detail call creates a separate BrowserContext and closes it immediately after reading, so it does not pollute an existing search session. The price number sprite images are downloaded and decoded through the Playwright request context.

Startup

.venv\Scripts\ziroom-mcp.exe

The service uses stdio by default; logs must not be written to stdout.

Using Streamable HTTP:

$env:ZIROOM_TRANSPORT="streamable-http"
$env:ZIROOM_HOST="127.0.0.1"
$env:ZIROOM_PORT="8000"
.venv\Scripts\ziroom-mcp.exe

The HTTP MCP endpoint is http://127.0.0.1:8000/mcp and uses a JSON response mode compatible with Cloudflare Quick Tunnel.

When going through a reverse proxy that forwards the public Host, additionally set $env:ZIROOM_BEHIND_PROXY="1". Once enabled, keep ZIROOM_HOST=127.0.0.1 to avoid listening directly on the public network interface.

Ziroom currently returns an empty body to headless Chrome, so the service launches a visible browser by default. Enable headless mode only after confirming that the target page supports it:

$env:ZIROOM_HEADLESS="1"
.venv\Scripts\ziroom-mcp.exe

You can also specify the Chrome/Edge executable via ZIROOM_CHROME_PATH.

The same search session always reuses the same browser tab. After filter-link navigation, the service preserves existing query parameters, restores isOpen to 1, and then re-locates the next item; if the site still hides the target link in the DOM, it uses a DOM click as a fallback.

Agent Calling Conventions

When scraping a single detail page, call get_listing_detail directly once; there is no need to create or close a search session:

{
  "url": "https://wh.ziroom.com/x/123456.html",
  "timeout_seconds": 30,
  "retries": 4,
  "include_report": true
}

The return value includes listing_id, url, fetched_at, a structured listing, and optional report_markdown.

When filtering listings, follow this order:

1. Call create_search_session.

2. Call get_filter_schema and select only the tags currently returned by the page.

3. location, area, and metro are mutually exclusive property search methods; keep only one. Build a fallback queue in the order location → area → metro. If the preferred option errors, is not retained, or returns zero results, confirm that the page has been restored before trying the next one.

4. All modification tools use the same session_id and pass the state_version returned by the previous step.

5. After each modification, check has_results.

6. If it is false, call restore_checkpoint with the checkpoint returned this time, and set reason to empty_results.

7. If it returns skipped=true and reason=page_did_not_retain_option, the page did not retain this tag and the tool has already restored the original state; do not call restore_checkpoint. Instead, refresh the schema and record it as unavailable, or retry a limited number of times according to business rules. Other modification tools correspondingly return reason=page_did_not_retain_change.

8. Finally call get_results and verify all conditions that should be retained via expected_filters.

9. After completing, call close_search_session.

Expected filter conflicts are not returned as tool errors. When the current page has no option, the option has already been applied, the page did not retain a change, or there is a location/area/metro conflict, the modification tool returns skipped=true and state_changed=false, keeping the original state_version and all selected conditions. The Agent should record the reason and continue to the next item. Real version conflicts, invalid sessions, site failures, and internal errors are still returned as tool errors.

Testing

All MCP tools have offline protocol-layer tests:

.venv\Scripts\python.exe -m pytest -m "not live" -v

The tests also start a stdio server subprocess that uses a fake web backend to verify MCP initialization, tool discovery, and tool invocation. ZIROOM_BACKEND=fake is for automated testing only.

Real-webpage smoke tests:

$env:ZIROOM_LIVE_TEST="1"
.venv\Scripts\python.exe -m pytest -m live -v