divar-mcp
Advanced tools
Unofficial read-only MCP server for Divar (divar.ir): search classified ads in any Iranian city, compare, find the cheapest and best deals, appraise prices, browse the map.
Let your AI agent search Divar (دیوار) ads in any Iranian city, and tell it whether a price is fair.
An unofficial, read-only MCP server for Divar, Iran's largest classifieds site (homes, cars, phones, jobs, services).
Search, read ads, compare, find the cheapest and best-value ads, appraise prices and browse the map from Claude, Cursor or Copilot. Prices are in Toman.
For AI agents · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development
uvx divar-mcp or claude mcp add divar -- uvx divar-mcp. Transport: stdio. Needs uv (Python 3.10+).DIVAR_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.dv_watch and dv_price_trend write, and only to a local file of your own searches.dv_. Start with dv_search, dv_post, dv_cheapest, dv_best_for_budget, dv_market.dv_cities / dv_categories -> dv_filters -> dv_search -> dv_post -> dv_similar / dv_appraise / dv_compare.divar://cities, divar://categories, divar://category-filters/{slug}; prompts compare_ads, best_under_budget, appraise_listing, watch_market.price for a sale; deposit + rent for a rental (rent 0 with full_deposit means رهن کامل); no price means negotiable.token between tools and next_cursor back as cursor.server.json and the iran-mcp catalog (TOOLS.md, servers.json, llms.txt).Divar is where Iranians buy and sell flats, cars and phones, but answering "what is a fair price for a 2-bedroom flat in Vanak?" means scrolling through dozens of ads and ignoring the fake prices. With divar-mcp an agent fetches the ads, drops placeholder prices, computes the median and quartiles of the asking prices, and tells you which ads are well below them.
You: Find the best 2-bedroom flat to rent in Vanak with a deposit under 1 billion Toman.
Agent: calls
dv_parse_query->dv_best_for_budget->dv_postIt lists the best-value ads against the median of the ads that fit, with the reasons for each score, then opens the one you pick.
dv_new_since with the last timestamp to see only new ads; keep saved searches and a daily median price trend locally; export results as CSV or JSON linesExample prompts:
You need uv. No API key or account.
claude mcp add divar -- uvx divar-mcp
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"divar": { "command": "uvx", "args": ["divar-mcp"] }
}
}
Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code above, or add to .vscode/mcp.json:
{
"servers": {
"divar": { "type": "stdio", "command": "uvx", "args": ["divar-mcp"] }
}
}
codex mcp add divar -- uvx divar-mcp
Or in ~/.codex/config.toml:
[mcp_servers.divar]
command = "uvx"
args = ["divar-mcp"]
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"divar": { "command": "uvx", "args": ["divar-mcp"] }
}
}
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It is a standard stdio MCP server: run uvx divar-mcp, or pip install divar-mcp and run divar-mcp.
An ad card has token, title, price (sale) or deposit + rent (rent 0 with full_deposit means رهن کامل), info (mileage, condition...), district, seller (agency label), age_h (hours since the last bump), photos, image (thumbnail URL, only from dv_search with thumbnails), chat, tag (paid promotion), url, and suspect_price when the price looks like a placeholder. Absent flags mean false. Default page size is 10 to 20 ads.
All tools start with dv_ and are annotated read-only, except dv_watch and dv_price_trend, which write only to a local file.
| Tool | What it does |
|---|---|
dv_cities | City ids for a name (1,177 cities); no query lists the biggest cities |
dv_districts | Neighbourhoods of a city with ids, centre and main streets |
dv_neighbours | Neighbourhoods adjacent to a district (Divar's list plus the nearest ones by distance) |
dv_locate | City, neighbourhood and street address of a GPS point |
dv_place_search | Map autocomplete: landmark or street to coordinates |
dv_place_mapping | Convert old Divar place ids to current ones |
dv_categories | The 236-node category tree; search by name, list children |
dv_filters | Every filter of a category: key, type, label, unit, options |
dv_filter_options | Brand and model keys (161 car brands), districts and other option lists, with typed search |
dv_suggest | The search box's suggestions and category guesses for some text |
dv_parse_query | A plain Persian request ("آپارتمان اجاره ونک زیر ۸ میلیارد") to dv_search arguments: city, neighbourhoods, price bounds, area (80 متری), category |
dv_boundary | Neighbourhood borders of a city (GeoJSON): the city box, or one neighbourhood's polygon |
| Tool | What it does |
|---|---|
dv_search | Search ads with city, category, text, districts, price, brand, photo, freshness and any category filter; multi-page merge, client-side age and keyword filters, cursor paging |
dv_count | How many ads match a search (capped at 10,000) |
dv_cheapest | The cheapest ads of a search; placeholder prices and far-below-median outliers skipped |
dv_best_for_budget | Within a budget: best value with an explainable deal_score (and reasons) against the median of the ads that fit (price per m2 for property for sale), and the most you can get; bait / co-op / loan titles are skipped |
dv_find_deals | Ads priced well below the median of a search, no budget needed; junk prices and bait titles removed |
dv_market | Price statistics (min, quartiles, median, max) plus breakdown by district and by day |
dv_appraise | Is an ad's price (or a price you give) high or low versus similar ads: percentile, verdict ("insufficient comparables" when the call is extreme but thin), confidence |
dv_new_since | Ads published after a timestamp: poll with the returned latest to watch a search |
dv_export | The ads of a search as CSV or JSON lines |
dv_nearby | Map ads around a point (category required), nearest first, with coordinates, distance and total price |
dv_watch | Saved searches: create, then check to get only the ads newer than the last check (local file) |
dv_price_trend | One median asking price per day for a search, kept locally, with change since the previous day |
dv_status | Is Divar reachable, latency, caches, saved watches and the tool list |
| Tool | What it does |
|---|---|
dv_post | Full ad: price, specs, features, description, images, map position, seller type, flags |
dv_posts | Up to 10 ads in one call, compact |
dv_compare | 2 to 6 ads side by side: prices and only the specs that differ |
dv_similar | Ads like this one (same brand and area, widening step by step) |
dv_seller | A seller's personal and business ad counts, business card (or "personal seller") and other ads |
dv_dealer | A business's public page: name, member since, first 11 ads |
AI agent (Claude, Cursor, Copilot, ...)
│
│ MCP over stdio
▼
divar-mcp (runs on your machine)
│
│ HTTPS
└──────▶ api.divar.ir ads, categories, places, map
divar-mcp runs locally and calls the same JSON gateway the divar.ir web app uses. It has no hosted server in between and no API key. Every POST it sends is a read-only query. Requests go out through a Chrome-impersonating client (TLS/HTTP2 fingerprint and headers), at most 2 at a time with a small random delay, and a failed call is retried up to twice. Divar's list answers are widget JSON; the server turns them into compact ad cards and computes rankings and statistics from the asking prices it fetched.
deposit (ودیعه) and rent (اجاره); rent 0 with full_deposit is رهن کامل.suspect_price flags placeholders, and rankings and statistics skip them and prices under a tenth of the median.city: "استان مشهد" (or province:مشهد) searches the whole province of that city; districts and boundaries need a city.dv_search sort and the price tools sort the ads fetched in the call, not the whole market. Paging is a time cursor (next_cursor -> cursor).age_h is the time since the last bump (نردبان), not since publication; only the ad page has the real publish time.dv_filters lists the keys of a category; filters a category lacks are reported in ignored, not silently dropped. Web URL slugs (car) work next to API slugs (light).approximate_location).url to open the ad.divar-mcp[browser] and run patchright install chromium; the server then clears it once with a headless browser. Without it, the call fails with a message saying so.Yes: this unofficial MCP server wraps the public JSON API the Divar website itself uses, so Claude, Cursor or Copilot can search ads, read details and compare prices. Divar's official Kenar API is for partners (OAuth and an API key) and is not used here.
It is unofficial, open source (MIT) and free. It is read-only, needs no account or API key, and runs on your machine with no hosted server in between.
No. Those need a Divar login and are deliberately left out.
It does not push. dv_new_since returns only ads newer than a timestamp, and dv_watch remembers that timestamp for a saved search (in ~/.divar-mcp/state.json, or DIVAR_MCP_STATE), so a scheduler (cron, a Claude Code loop) can call dv_watch with action: "check".
Toman. Divar's API already uses Toman, so nothing is converted.
Add the server with claude mcp add divar -- uvx divar-mcp, or use the matching config in Quick start, then ask in plain language, in Persian or English.
Yes. dv_categories lists the 236-node category tree and dv_filters shows the filters of each category (brand and model, mileage, price and so on), so the same search tools work across categories.
npx @modelcontextprotocol/inspector uvx divar-mcp
| Variable | Default | Meaning |
|---|---|---|
DIVAR_MCP_PROXY | unset | Optional HTTP proxy URL for requests to divar.ir, or a comma-separated list: one is used until it gets blocked or fails to connect, then the next. System proxy settings are ignored |
DIVAR_MCP_STATE | ~/.divar-mcp/state.json | File for saved watches and price history (used by dv_watch and dv_price_trend) |
divar-mcp یک سرور MCP غیررسمی و فقطخواندنی برای دیوار، بزرگترین سایت نیازمندی ایران، است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد در آگهیهای هر شهر ایران (خرید و فروش و اجاره خانه، خودرو، موبایل و ...) جستجو کند، آگهی را کامل ببیند، چند آگهی را مقایسه کند و ارزانترین و مناسبترین آگهی را برای یک بودجه پیدا کند.
چه کارهایی میکند
نکتهها
DIVAR_MCP_PROXY را تنظیم کنید.نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add divar -- uvx divar-mcp
در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسشها
git clone https://github.com/sepehr071/divar-mcp && cd divar-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q # offline, recorded fixtures
uv run python -m pytest -m live -q # real API, one test per tool
uv build
Tools live in src/divar_mcp/ (places.py, catalog.py, search.py, post.py, market.py, watch.py, meta.py); each is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome.
Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions publishes to PyPI.
Unofficial and not affiliated with or endorsed by Divar. It reads public data through the endpoints of the divar.ir web app, which can change without notice. Everything it returns is asking prices typed by sellers, not advice. Keep request rates low.
If this saves you clicks, a star helps others find it.
Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.
FAQs
Unofficial read-only MCP server for Divar (divar.ir): search classified ads in any Iranian city, compare, find the cheapest and best deals, appraise prices, browse the map.
The pypi package divar-mcp receives a total of 460 weekly downloads. As such, divar-mcp popularity was classified as not popular.
We found that divar-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.