Torob

torob-mcp: Torob MCP server for AI agents

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.

For AI agents

• What: unofficial MCP server (model context protocol) for Torob (ترب), an Iranian price-comparison site. Persian and Finglish queries work; prices in Toman.
• Install: uvx torob-mcp or claude mcp add torob -- uvx torob-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional TOROB_MCP_PROXY (HTTP proxy, or a comma-separated list; Torob blocks many foreign and cloud IPs).
• Access: read-only. It cannot log in, buy, bookmark or set price alerts, so no confirmation is needed before calling any tool.
• Tools: 26, all prefixed 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.
• Units: prices in Toman (Torob's API is already Toman; nothing is converted). price is null, never 0, when there is no usable price.
• Use when: the user wants the best Iranian shop price for a product, a price history, installment or warranty offers, or a pick within a budget.
• Do not use when: the user wants to buy, or needs their own Torob account data (watchlist, alerts).
• Output: compact JSON. The product id (a UUID) passes between tools; links are https://torob.com/p/ / (not repeated on every card; tb_product_url and csv output still give them).
• Network: talks to 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.
• Machine-readable: server.json and the iran-mcp catalog (TOOLS.md, servers.json, llms.txt).

Why

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.

What it can do

• Search with category, brand (by name), price range, new / used, in-person, installment and attribute filters; weak matches are flagged (low_confidence, unmatched_terms, suggested queries)
• Every shop's offer for a product with score, warranty, installments, delivery and Torob's order-volume notes; offers flagged as unreliable are hidden and kept out of the statistics
• In-person stores with address, hours, open now and the age of the shelf price
• Price chart (about a year, weekly) with a great / fair / high verdict, price moves, and a 0-100 deal score
• Decision tools: cheapest trustworthy offer for a name, compare 2-5 products (only the differing specs), best picks under a budget, cheapest shop for a whole basket (single shop vs split cart)
• Shop profiles (score, e-Namad seal, time on Torob, delivery terms), shop search, shop catalogue
• CSV export of search results and seller lists
• Read-only by design: no login, no alerts, no purchases

Example prompts:

• "Cheapest trustworthy shop for an iPhone 13 Pro 256 GB, and is now a good time to buy?"
• "Compare the Galaxy A55 and the Redmi Note 13 Pro. Which one is worth the price difference?"
• "Which shops sell this laptop with installments and a warranty?"
• "Best 55-inch TVs under 30 million Toman."
• "Cheapest single shop for: a kettle, a toaster and an electric grill. Is splitting the cart cheaper?"
• ارزان‌ترین فروشنده معتبر آیفون ۱۳ پرو ۲۵۶ کجاست و الان وقت خرید هست؟
• نمودار قیمت این گوشی در یک سال گذشته را نشان بده.
• ارزان‌ترین فروشگاهی که همه این سه کالا را دارد کدام است؟

Quick start

You need uv. No API key or account.

Claude Code

claude mcp add torob -- uvx torob-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

{

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

</details>

Cursor

Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json.

VS Code (Copilot agent mode)

Click Install in VS Code above, or add to .vscode/mcp.json:

{

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

</details>

Codex CLI

codex mcp add torob -- uvx torob-mcp

Or in ~/.codex/config.toml:

[mcp_servers.torob]

command = "uvx" args = ["torob-mcp"]

</details>

Gemini CLI

Add to ~/.gemini/settings.json:

{

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

</details>

Windsurf

Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.

Anything else

It's a standard stdio MCP server: run uvx torob-mcp, or pip install torob-mcp and run torob-mcp.

Tools

All tools are read-only and start with tb_. A product is identified by its id (a UUID); every tool also accepts a /p/ /... path or a full torob.com product URL.

Find products (8)

One product (10)

Decide (5)

Shops (3)

All 26 tools are annotated readOnlyHint: true and return compact JSON, so they don't flood the agent's context.

How it works

  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.

Good to know

• Prices are Toman. Torob's API already returns Toman (checked against the display text in every test); nothing is converted. price is null when there is no usable price, never 0.
• A card's price is the cheapest across shops and can be an out-of-stock or unreliable offer. For a real buying price use tb_sellers or tb_cheapest, which skip offers flagged unreliable.
• **Torob's bot pro