Divar

divar-mcp: Divar MCP server for AI agents

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.

[PyPI] [Python] [CI] [MCP Registry] [License: MIT]

[Install in VS Code]

For AI agents · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development

For AI agents

• What: unofficial MCP server (model context protocol) for Divar (دیوار, divar.ir), Iran's classifieds site. Persian queries work best; Arabic letter variants (ي/ك) are folded.
• Install: uvx divar-mcp or claude mcp add divar -- uvx divar-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional DIVAR_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
• Access: read-only on Divar. It cannot log in, post, chat, bookmark or reveal a seller's phone number, so no confirmation is needed before calling a tool. Only dv_watch and dv_price_trend write, and only to a local file of your own searches.
• Tools: 31, all prefixed dv_. Start with dv_search, dv_post, dv_cheapest, dv_best_for_budget, dv_market.
• Typical sequence: dv_cities / dv_categories -> dv_filters -> dv_search -> dv_post -> dv_similar / dv_appraise / dv_compare.
• Also: resources divar://cities, divar://categories, divar://category-filters/{slug}; prompts compare_ads, best_under_budget, appraise_listing, watch_market.
• Units: prices in Toman (Divar's own unit, nothing is converted). price for a sale; deposit + rent for a rental (rent 0 with full_deposit means رهن کامل); no price means negotiable.
• Use when: the user wants to find, price-check or monitor Divar ads (flats to buy or rent, used cars, phones, furniture, jobs...), or asks what something costs in a city.
• Do not use when: the user wants to post an ad, message a seller or get a phone number (login-only on Divar), or needs a market other than Divar.
• Output: compact JSON ad cards. Pass token between tools and next_cursor back as cursor.
• Machine-readable: server.json and the iran-mcp catalog (TOOLS.md, servers.json, llms.txt).

Why

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_post

It 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.

What it can do

• Search ads in one or several cities by category, text, neighbourhood, price (and deposit for rentals), brand and model, photo, freshness and every other filter of the category; merge several pages with duplicates removed; continue with a cursor
• Read a full ad: price in Toman, specs, features, description, all images, map position, seller type, placeholder-price detection
• Find value: cheapest ads (junk prices skipped), best value and most-for-the-budget, ads priced well below the median, side-by-side comparison showing only the differences, similar ads
• Judge a price: fair-price appraisal with percentile and confidence, market statistics by district and by day
• Monitor: poll 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 lines
• Use the map: ads around a GPS point or landmark with distances; neighbourhoods, neighbours, borders, address of a point
• Look at sellers and dealers: how many ads a seller has, the business card and its ads

Example prompts:

• "Cheapest used Peugeot 206 in Tehran, and is it priced fairly compared with similar ads?"
• "Find apartments to rent near Vanak under 8 billion Toman and compare the top three."
• "Show new iPhone 15 ads in Mashhad since this morning."
• "What is the median price per square metre for apartments for sale in Gisha?"
• ارزان‌ترین آپارتمان ۲ خوابه اجاره‌ای در ونک با ودیعه زیر ۱ میلیارد کدام است؟
• قیمت این ماشین نسبت به آگهی‌های مشابه گران است یا ارزان؟
• آگهی‌های جدید گوشی آیفون ۱۵ در مشهد را از امروز صبح نشان بده.

Quick start

You need uv. No API key or account.

claude mcp add divar -- uvx divar-mcp

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

{  "servers": {    "divar": { "type": "stdio", "command": "uvx", "args": ["divar-mcp"] }  }}

codex mcp add divar -- uvx divar-mcp

[mcp_servers.divar]command = "uvx"args = ["divar-mcp"]

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

Tools

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.

Find places and categories

Search and price

One ad and its seller

How it works

  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.

Good to know

• Prices are Toman. Divar's prices are Toman already; nothing is converted. A missing price means negotiable (توافقی), never 0. Rentals have deposit (ودیعه) and rent (اجاره); rent 0 with full_deposit is رهن کامل.
• Asking prices. Everything is what sellers typed, not what deals close at. Some sellers type junk (1,111,111 or a deposit as a car price): suspect_price flags placeholders, and rankings and statistics skip them and prices under a tenth of the median.
• Province scope. city: "استان مشهد" (or province:مشهد) searches the whole province of that city; districts and boundaries need a city.
• Order. Divar's API only returns newest first; the first 1-3 rows can be paid promotions with older dates. 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).
• Freshness. age_h is the time since the last bump (نردبان), not since publication; only the ad page has the real publish time.
• Filters. 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).
• Map positions of most ads are fuzzed by about 500 m (approximate_location).
• No phone numbers. Divar shows them only to logged-in users; this server never logs in. Use url to open the ad.
• Large prices. Detail prices come from the ad's price rows; Divar's raw number elsewhere in the ad is float-rounded for large values.
• Not available: a Divar price valuation from the site itself, sort by price on Divar's side, paging through all of a dealer's ads, anything behind login.
• Rate limits: none was seen in testing, but keep calls modest.
• Bot check: if Divar ever serves a challenge page, install 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.

FAQ

npx @modelcontextprotocol/inspector uvx divar-mcp

Configuration

فارسی: سرور MCP دیوار

claude mcp add divar -- uvx divar-mcp

Development

git clone https://github.com/sepehr071/divar-mcp && cd divar-mcpuv syncuv run ruff check . && uv run ruff format --check .uv run python -m pytest -q            # offline, recorded fixturesuv run python -m pytest -m live -q    # real API, one test per tooluv 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.

Related servers

• iran-mcp: catalog of all Iranian-service MCP servers
• digikala-mcp for Digikala products and prices
• torob-mcp for price comparison across Iranian shops on Torob
• snapp-mcp for Snapp
• technolife-mcp for Technolife electronics
• jabama-mcp for Jabama stays
• mcpfarsi.ir: Persian marketplace of MCP servers for Iranian services

Disclaimer

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.

Author

[Sepehr Radmard: open-source MCP servers for the Iranian web. LinkedIn: linkedin.com/in/sepehr-radmard]

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.

License

MIT