zameen-mcp 0.3.0

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

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

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.