torob-mcp
Advanced tools
Unofficial read-only MCP server for Torob: search Iranian shops, compare seller prices, price history, deal checks, baskets, installments, shops.
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.
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.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.
claude mcp add torob -- uvx torob-mcp
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"torob": { "command": "uvx", "args": ["torob-mcp"] }
}
}
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:
{
"servers": {
"torob": { "type": "stdio", "command": "uvx", "args": ["torob-mcp"] }
}
}
codex mcp add torob -- uvx torob-mcp
Or in ~/.codex/config.toml:
[mcp_servers.torob]
command = "uvx"
args = ["torob-mcp"]
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"torob": { "command": "uvx", "args": ["torob-mcp"] }
}
}
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.
| Tool | What it does |
|---|---|
tb_search | Search with sort, category, brand name or id, price range, new / used, in-person, installment, city and validated attribute filters; csv output |
tb_suggest | Torob's autocomplete (fixes Finglish and colloquial wording); works even while other calls are blocked |
tb_filters | Category children, brands, price span, sort options and attribute slugs / values for a query or category |
tb_category | A category page: parents, sub-categories and top products |
tb_brands | All brands of a category with ids |
tb_trends | What people search right now, with a sample product each |
tb_offers | The special-offers feed: themed rows of discounted products |
tb_cities | City ids (most visited, or search by name) for the city filters |
| Tool | What it does |
|---|---|
tb_product | Name, price window, category path, brand, key specs (full table on request), cheapest offer |
tb_sellers | Every online shop offer with score, warranty, installments, delivery, buyer notes; min / median / max and spread; city, installment, warranty and score filters; csv output |
tb_stores | In-person stores: address, hours, open now, shelf price and age, optional map coordinates |
tb_presence | Counts of online shops, in-person stores, installment shops and Torob-warranty shops |
tb_variants | Sibling variants (storage + RAM, colour, region) with their own prices |
tb_price_chart | Weekly minimum and average price for about a year with a buy-now verdict |
tb_price_history | Notable price drops and rises, lowest and highest point, last change |
tb_similar | Products Torob shows as alternatives |
tb_product_url | Clean torob.com link from an id, path or URL (no request) |
tb_products_batch | Short records for up to 10 products |
| Tool | What it does |
|---|---|
tb_cheapest | Cheapest trustworthy offer for a product named in words (checks every shop of the top matches; installment and city options) |
tb_compare | Compare 2-5 products: only the differing specs, price window, cheapest flagged |
tb_best_value | Ranked picks under a budget in Toman (by budget reach, popularity or price) |
tb_deal_check | Deal score 0-100 from the price history and today's offers, for today's price or a price you were offered |
tb_basket | Cheapest single shop that sells every item of a list, and the split-cart total |
| Tool | What it does |
|---|---|
tb_shop | Shop trust profile: score, votes, e-Namad seal, time on Torob, city, website, delivery and payment terms |
tb_find_shops | Find shops by name or domain, optionally by city |
tb_shop_products | Products a shop sells, with the price range of the page |
All 26 tools are annotated readOnlyHint: true and return compact JSON, so they don't flood the agent's context.
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, shops
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.
| Variable | Default | Meaning |
|---|---|---|
TOROB_MCP_PROXY | unset | HTTP proxy for every request, e.g. http://user:pass@host:port. A comma-separated list is used one at a time: the next proxy takes over when one gets a challenge or cannot connect |
TOROB_MCP_MIN_INTERVAL | 2 | Seconds between upstream requests (random jitter of 0.5-2 s comes on top) |
TOROB_MCP_BROWSER | on | 0 turns off the headless-browser fallback even when torob-mcp[browser] is installed |
torob-mcp یک سرور MCP غیررسمی و فقطخواندنی برای ترب، موتور مقایسه قیمت ایران، است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد قیمت یک کالا را در فروشگاههای ایرانی مقایسه کند.
چه کارهایی میکند
نکتهها
null است، نه صفر.TOROB_MCP_PROXY خروجی دیگری بدهید.کلیدواژهها: ترب، torob، سرور MCP ترب، مقایسه قیمت، ارزانترین قیمت، ارزانترین فروشنده، تاریخچه قیمت، نمودار قیمت، خرید قسطی، گارانتی، سبد خرید، فروشگاه اینترنتی.
نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add torob -- uvx torob-mcp
در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسشها
git clone https://github.com/sepehr071/torob-mcp && cd torob-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; skips (does not fail) when Torob answers 490
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.
FAQs
Unofficial read-only MCP server for Torob: search Iranian shops, compare seller prices, price history, deal checks, baskets, installments, shops.
We found that torob-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.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.