MCP 服务器

zameen-mcp

Enables AI assistants to research Zameen.com property listings with verified/titanium filtering, local watchlists, listing details, and agent-message drafting through structured tools.

README

MCP server for researching property listings on Zameen.com

Verified / Titanium-agent filtering · local watchlists · listing details · agent-message drafting — through 9 structured tools in any MCP client.

Tool reference · Deployment guide · Contributing · Changelog

</div>

An MCP (Model Context Protocol) server for researching property listings on Zameen.com — Pakistan's largest real estate portal — through structured tools instead of fragile screen scraping.

Trademark notice: "Zameen" and the Zameen.com logo are trademarks of Zameen.com (EMPG). They are used here solely to identify the service this tool interfaces with. This project is unaffiliated with, and not endorsed by, Zameen.com.

Works with any MCP client: Claude Desktop, Hermes Agent, Cursor, and others.

Install

# run directly with no permanent install (recommended)
uvx zameen-mcp

# or install as an isolated CLI tool
pipx install zameen-mcp

Register in your MCP client

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

That's it — 9 tools appear in your AI client.

Tools

Tool	What it does
`search_properties`	Structured search: city, purpose, type, beds, price, area, keywords, sort
`get_listing_details`	Full detail page for one listing (URL or numeric id)
`list_supported_cities`	Verified city slugs + property types
`add_watch` / `check_watch`	Save search criteria locally; later re-checks report only NEW listings
`list_watches` / `remove_watch`	Manage saved watches
`draft_agent_message`	Compose a polite inquiry for a listing — draft only, never sends
`account_status`	Whether an authenticated session is loaded

Badge-level filtering Zameen's own UI can't do: verified_only, agent_tier (e.g. "titanium"), exclude_promoted.

Full parameter reference + natural-language cheat sheet: docs/TOOLS.md

Optional: log in to your Zameen account

Anonymous searching works out of the box. To also ride your logged-in session (saved searches, personalized pages):

pipx inject zameen-mcp playwright && .venv/bin/playwright install chromium   # pipx
uv tool install zameen-mcp --with playwright && playwright install chromium  # uv

zameen-mcp-login   # opens a Chromium window; YOU log in; cookies stay local

Your password is never seen or stored by this software — only the resulting session cookies, kept in ~/.zameen-mcp/ on your machine. Wipe anytime: zameen-mcp-login --logout.

Data location

All state lives in ~/.zameen-mcp/ (watches.json, session_state.json, chrome-profile/). Override with the ZAMEEN_MCP_HOME environment variable. Treat session_state.json like a password: it grants access to your account while valid.

Development

git clone <repo-url> && cd zameen.com
uv venv .venv && uv pip install -p .venv/Scripts/python.exe -e ".[dev]"
.venv/Scripts/python.exe -m pytest -q          # offline suite against real captured pages
.venv/Scripts/python.exe smoke_test.py         # live end-to-end check

Compliance & fair use

Zameen.com's robots.txt disallows crawling its major-city listing pages. This server is built for interactive, human-paced research — a person asking their assistant questions — not bulk harvesting or redistribution.
Requests go out one at a time with browser-like headers. Don't remove the pacing or loop searches unattended.
Listing data belongs to Zameen.com and its advertisers; "Zameen" is a trademark of Zameen.com. This project is unaffiliated and not endorsed.
Prices are agent-entered, as-listed — not verified market valuations.

Limitations

Read-only by design: no posting, messaging, or account changes — contacting agents is deliberately a human action (draft_agent_message only drafts).
Badge filters operate on fetched result pages (up to 3 per call).
Parsing targets Zameen's current HTML; site redesigns may require parser updates (fixtures make regressions easy to catch).

MIT licensed — see LICENSE.