io.github.sepehr071Published by GitHub account sepehr071v0.2.0Updated Nov 8, 2026
Unofficial read-only Torob: compare Iranian shop prices, price history, deal checks and baskets.
Unofficial, read-only MCP server that lets an assistant search Torob and compare prices, offers, price history and shops for products in Iran.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
Let your AI agent compare prices across Iranian shops on Torob (ترب).
An unofficial, read-only MCP server for Torob, Iran's price-comparison engine: search a product, see every shop's offer,
check the price history, judge a deal and find the cheapest shop for a whole shopping list, all from Claude, Cursor or Copilot.
[PyPI] [Python] [CI] [MCP Registry] [License: MIT] [mcpfarsi]
[Install in Cursor] [Install in VS Code]
For AI agents · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development · Related
Status: new. The live test suite passes against torob.com (checked 2026-10-18). Some endpoints are still mapped from the web app's code only, and several offline test fixtures are hand-made rather than recorded.
uvx torob-mcp or claude mcp add torob -- uvx torob-mcp. Transport: stdio. Needs uv (Python 3.10+).TOROB_MCP_PROXY (HTTP proxy, or a comma-separated list; Torob blocks many foreign and cloud IPs).tb_. Start with tb_search, tb_sellers, tb_cheapest, tb_deal_check, tb_basket.
Typical sequence: tb_search -> tb_sellers (every shop) -> tb_price_chart / tb_deal_check; tb_cheapest for "where is X cheapest"; tb_compare to choose between models.price is null, never 0, when there is no usable price.id (a UUID) passes between tools; links are https://torob.com/p/<id>/ (not repeated on every card; tb_product_url and csv output still give them).api.torob.com directly from your machine. After a bot-protection block (HTTP 490) it stops calling for 30 minutes and reports the minutes left; set TOROB_MCP_PROXY for another exit.server.json and the
iran-mcp catalog (TOOLS.md, servers.json, llms.txt).Torob lists one product with the offers of many shops, but judging them takes clicks: which offers are reliable,
who gives a warranty or installments, whether today's price is high compared to the last year, and which single
shop can sell your whole list. An agent with torob-mcp answers that in a few calls, and skips offers Torob itself flags as unreliable.
low_confidence, unmatched_terms, suggested queries)Example prompts:
You need uv. No API key or account.
Settings → Developer → Edit Config, then add:
Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json.
Click Install in VS Code above, or add to .vscode/mcp.json:
Or in ~/.codex/config.toml:
Add to ~/.gemini/settings.json:
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It's a standard stdio MCP server: run uvx torob-mcp, or pip install torob-mcp and run torob-mcp.
All tools are read-only and start with tb_. A product is identified by its id (a UUID); every tool also accepts
a /p/<id>/... path or a full torob.com product URL.
All 26 tools are annotated readOnlyHint: true and return compact JSON, so they don't flood the agent's context.
torob-mcp runs locally and calls the same public JSON endpoints the torob.com web app uses. There is no hosted
server in between and no API key. Requests go one at a time with a pause between them, and replies are cached.
price is null when there is no usable price, never 0.tb_sellers or tb_cheapest, which skip offers flagged unreliable.TOROB_MCP_MIN_INTERVAL), and caches replies (5 min for searches, 15 min for products, 6 h for charts). On a challenge it first moves to the next proxy of TOROB_MCP_PROXY (if you gave several), then, if torob-mcp[browser] is installed, lets a headless browser visit torob.com once and reuses its cookies. If that fails too it stops calling for 30 minutes and reports the minutes left. It does not solve CAPTCHAs. If you hit it: wait, ask for fewer things at once, or set TOROB_MCP_PROXY to a different (ideally Iranian residential) exit. tb_suggest is not covered by that limit.count_capped).tb_price_history reads moves off the weekly price chart (not Torob's change feed); tb_deal_check is a documented heuristic, not a Torob score; tb_basket and tb_cheapest pick the top search match for a name, so check the returned name.price-change-info and a category tree with product counts. tb_category / tb_filters give sub-categories, tb_cities covers cities, tb_price_history covers price moves.condition=used.Yes: torob-mcp is an unofficial MCP server with 26 read-only tools. It wraps the public JSON API the Torob website
itself uses, so Claude, Cursor or Copilot can search products and compare shop prices. No API key is needed.
Add the server with claude mcp add torob -- uvx torob-mcp (or the matching config in Quick start
for Claude Desktop, Cursor and VS Code), then ask in plain language, in Persian, Finglish or English.
It is unofficial and not affiliated with Torob. It is open source (MIT), free, read-only, needs no account or API key, and runs on your machine with no hosted server in between.
Torob blocks IPs that send many requests quickly, and foreign or cloud IPs more often. Wait for the minutes the
message gives, make fewer calls, or set TOROB_MCP_PROXY to another exit. Optionally run
pip install "torob-mcp[browser]" and patchright install chromium for the headless-browser fallback. The server
never tries to solve CAPTCHAs.
Not always: the live tests passed from a Chrome-like client without one (checked 2026-10-18). Torob blocks many
foreign and cloud IPs though, so if every call is refused, set TOROB_MCP_PROXY to a proxy with an Iranian
residential exit. Normal system proxy variables are ignored on purpose.
No, and that is deliberate. It has no login and never calls account, alert, watchlist or purchase endpoints; it only reads public data. The agent finds the best option, you buy on the shop's site.
Toman. Torob's API already answers in Toman and nothing is converted.
No. Torob has no buyer reviews or Q&A of its own. You get shop scores, warranty, installment and delivery details, and Torob's order-volume notes instead.
uvx is not foundUse the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
The server calls api.torob.com directly and ignores system proxy variables. All variables are optional.
torob-mcp یک سرور MCP غیررسمی و فقطخواندنی برای ترب، موتور مقایسه قیمت ایران، است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد قیمت یک کالا را در فروشگاههای ایرانی مقایسه کند.
چه کارهایی میکند
نکتهها
null است، نه صفر.TOROB_MCP_PROXY خروجی دیگری بدهید.کلیدواژهها: ترب، torob، سرور MCP ترب، مقایسه قیمت، ارزانترین قیمت، ارزانترین فروشنده، تاریخچه قیمت، نمودار قیمت، خرید قسطی، گارانتی، سبد خرید، فروشگاه اینترنتی.
نصب (اول uv را نصب کنید). در Claude Code:
در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسشها
Tools live in src/torob_mcp/ (search.py, product.py, decide.py, shops.py); each is a typed async function
with a docstring that tells the agent when to use it. A unit test keeps the tool tables in this README equal to the
server's tool list. Issues and PRs are welcome.
Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions tests,
publishes to PyPI and the MCP Registry, and creates the GitHub Release.
Unofficial and not affiliated with or endorsed by Torob. It is read-only and uses the public endpoints of the torob.com web app, which can change without notice. Please keep request rates low.
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.
If this saves you clicks, a star helps others find it.
Source: README.md at commit 35e0606
Search products
Search Torob for products; each card has the cheapest shop price (Toman) and the shop count. Weak matches set `low_confidence` and `unmatched_terms`; `spellcheck` / `suggested_queries` help rephrase. `price_span` is the span of the unfiltered result.
citypagesortbrandlimitqueryoutputfilterscategoryconditionin_personmax_price+3 moreSuggestions
Torob's autocomplete: up to 8 search phrases for typed text (fixes Finglish and colloquial wording). Use before tb_search. Works even while other calls are blocked.
textrequiredSearch filters
Which filters exist for a query/category: sub-categories, brands, price span, sort options, attributes. Use before tb_search for category / brand ids or the attribute slugs and values of `filters`.
querycategoryBrowse category
A category page: its parents, sub-categories and top products. Use to walk the category tree. For text search in a category use tb_search(category=).
pagesortbrandlimitcategoryrequiredmax_priceBrands
All brands of a category with their ids (for tb_search brand=).
limitsearchcategoryrequiredSearch trends
What people search on Torob right now, each with its category and one sample product.
limitSpecial offers
Torob's special-offers feed ("پیشنهاد ویژه"): themed rows with discounted or promoted products.
pagesizelimitCities
City ids for `city` arguments (392 Tehran, 468 Mashhad, 240 Isfahan).
limitsearchProduct details
Full record of one product: name, price range (Toman), category, brand, key specs, cheapest offer. `price_min`/`price_max` include unreliable offers; `cheapest_offer` is the cheapest usable one on the page.
productrequiredfull_specsSellers
Every online shop offer for a product, cheapest first, with trust, warranty, installment and delivery info. Use to pick where to buy. `score`/`votes`: shop rating 0-5; `unreliable`: bait or stale price; `buyer_notes`: Torob's order-volume and complaint notes; `updated`: price age. `stats` cover usable offers only.
citylimitoutputproductrequiredmin_scorewarranty_onlyinstallment_onlyinclude_unreliableIn-person stores
In-person shops that stock a product: address, opening hours, open now, shelf price and its age. Use for "can I buy it today near me". Online offers: tb_sellers.
citylimitproductrequiredwith_locationShop presence
How widely a product is sold: online shops, in-person stores, installment and warranty shops, price window.
productrequiredVariants
Sibling variants of a product (storage + RAM, colour, region ...) each with its own cheapest price.
productrequiredPrice chart
Price chart of a product (about a year, weekly): minimum and average price in Toman, with a buy-now verdict. `summary.verdict` (great / fair / high) follows `percentile`: share of weeks cheaper than now.
pointsproductrequiredPrice history events
Notable price moves of a product, newest first, with the lowest and highest point. Weekly moves of the chart's minimum price; a negative `change_pct` is a drop.
limitproductrequiredmin_change_pctSimilar products
Products Torob shows as similar (alternatives in the same class), with cheapest price and shop count.
limitproductrequiredProduct URL
Clean torob.com URL for a product id, path or link (no request is sent).
productrequiredProduct cards
Short records (name, price window, shop counts, category, brand) for up to 10 products at once. One request per product; failures go to `errors`.
productsrequiredCheapest offer
Cheapest trustworthy offer for a product named in words: searches, then looks at every shop's offer. Gives the best usable offer per top match and the overall `cheapest`; check the matched name.
cityqueryrequiredconditionmin_scorecandidatesinstallment_onlyCompare products
Side-by-side comparison of 2-5 products: only the specs that differ, the price window, and which is cheapest. `differences` maps a spec to its values in `products` order (null = not listed).
productsrequiredBest value under budget
Ranked product picks that fit a budget (Toman), for "best phone under 30 million". No quality score: check specs with tb_compare. In-stock products only.
limitquerybudgetrequiredrank_bycategoryconditionmin_shopsDeal check
Is this a good price? Score 0-100 from the product's price history and today's competing offers. 100 minus the price's percentile among past weekly minimums, minus up to 20 when above today's cheapest usable offer. `reasons` explains it.
priceproductrequiredShopping basket
Cheapest shop for a whole shopping list: best single shop that sells everything, and the split-cart total. Names resolve to the top search match (check `items[].name`; pass ids to be exact).
cityitemsrequiredconditionmin_scoreinstallment_onlyShop profile
A shop's trust profile: score and votes, e-Namad seal, time on Torob, city, website, delivery and payment terms. Use to vet a seller from tb_sellers. Contact details are left out.
shop_idrequiredFind shops
Find shops in Torob's directory by name or domain; returns ids for tb_shop and tb_shop_products.
citykindpagelimitqueryrequiredShop catalogue
Products one shop sells on Torob, with the price range of the page. Card prices are the cheapest across all shops; tb_sellers gives this shop's own offer.
pagesortlimitqueryshop_idrequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
claude mcp add torob -- uvx torob-mcp{ "mcpServers": { "torob": { "command": "uvx", "args": ["torob-mcp"] } }}{ "servers": { "torob": { "type": "stdio", "command": "uvx", "args": ["torob-mcp"] } }}codex mcp add torob -- uvx torob-mcp[mcp_servers.torob]command = "uvx"args = ["torob-mcp"]{ "mcpServers": { "torob": { "command": "uvx", "args": ["torob-mcp"] } }} AI agent (Claude, Cursor, Copilot, ...) │ │ MCP over stdio ▼ torob-mcp (runs on your machine) │ │ HTTPS, Chrome-like client └──────▶ api.torob.com products, sellers, stores, price charts, shopsclaude mcp add torob -- uvx torob-mcpgit clone https://github.com/sepehr071/torob-mcp && cd torob-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; skips (does not fail) when Torob answers 490