Torob MCP - Price comparison intelligence for AI agents

A public MCP server that gives AI agents real Torob knowledge: search Iran's price-comparison engine, prices in Toman, every seller's offer on one product, price history and trends, shop profiles, in-person sellers, shop grades and cities, delivery options, Torob's own filters, category tree, provinces and cities, and the deals it is featuring right now. Read-only, no key needed. No login, ever.

Live endpoint: https://torob-mcp.mmdju3.workers.dev/mcp (Streamable HTTP, stateless) - opening the bare address in a browser shows the site, and GET /mcp gets the connect page instead of a JSON error.

نسخه فارسی · Examples · Tool reference · Changelog

Connect in 30 seconds

Any MCP client, one URL. Cline / Cursor / Claude Desktop (mcp.json style):

{
  "mcpServers": {
    "torob": { "url": "https://torob-mcp.mmdju3.workers.dev/mcp" }
  }
}

Then just talk: "ارزون‌ترین آیفون ۱۳ کجاست؟", "هدفون زیر ۱۰ میلیون", "این گوشی رو کجا بخرم بهتره؟", "چی تخفیف خورده؟".

Agents running in a browser work too - the endpoint answers CORS preflights (OPTIONS /mcp).

14 tools

Every tool is read-only (readOnlyHint: true) and needs no credentials. Nothing here can order, message or contact a shop.

Notes for agent builders:

• All prices are in Toman (1 Toman = 10 Rial). Prices, stock and shop grades move constantly - always link the product URL so the user can confirm before buying.
• A search card is one price - the cheapest offer. product_details is the call that lists every seller, and the price_spread_toman between them is the whole reason a price-comparison source exists. It also returns the shops that sell the product in person (in_person_sellers), with each shelf price's last_price_change_date - a shop price can be months old, so say how old it is.
• price_history is the honesty check on a price. Compare today's cheapest offer with what Torob charts for the product; the series labels are Torob's own, so quote them rather than inventing a trend.
• price_toman: null means not available - out of stock upstream, or no price at all. It is never 0, and 0 is never free: Torob's own "not for sale" comes back as available: false.
• price_unreliable: true is Torob saying that price cannot be trusted. Pass the warning on; do not present it as a bargain.
• A shop grade needs its vote count. Torob sends a score for nearly every offer but almost never the votes behind it, so shop_score: 5 with shop_votes: 0 is normal and means "no votes yet", not "five-star shop".
• An empty result is not proof a product does not exist. The response carries query_note plus Torob's own suggested_queries - retry with one of them instead of telling the user it is unavailable.
• An unknown filter slug or value is refused with the real ones. available_filters carries each group's accepted values (options, plus values_url for the full brand list); Torob ignores a slug or value it does not know and answers unfiltered, so a typo used to hand back a full unfiltered list that read as a filtered answer.
• Torob answers a client that calls too fast with a bot challenge instead of data. The server reports it plainly, never solves or evades it, and holds the rest of a burst for five minutes rather than retrying into a longer block. Details in SECURITY.md.
• Results are capped (default 10, max 30) to protect agent context. Persian wording is folded (Arabic yeh/kaf, Persian and Arabic-Indic digits, ZWNJ kept) when cache keys and product names are compared - the query itself reaches Torob exactly as typed, and Torob folds it the same way.
• examples/sample-calls.md has eleven copy-paste flows, and docs/tools.md has every parameter and filter slug. Response types live in docs/card.d.ts.

How it works

How a question becomes an answer. No user data is stored anywhere in this path.

flowchart LR
    subgraph you [Your machine]
        agent[AI agent<br/>Cline / Cursor / Claude]
    end
    subgraph cf [Cloudflare Workers]
        worker[torob-mcp<br/>stateless, no database]
    end
    tr[(Torob public web API<br/>api.torob.com)]

    agent -->|POST /mcp<br/>Streamable HTTP, no key| worker
    worker -->|HTTPS + polite pacing<br/>reads only| tr
    tr -->|large JSON, seller lists| worker
    worker -->|small records<br/>toman, offers, URL| agent

What this means:

• Stateless. Every request stands alone - no sessions, no accounts, nothing to log in to.
• Read-only. All 14 tools carry readOnlyHint. Nothing here can change, delete or order anything, and no shop is ever contacted.
• Projected, not passed through. A Torob search page is roughly 70KB of ranking metadata and experiment plumbing. Every tool returns a compact record built by the server's projection layer instead, with the seller list as a first-class offers[] array rather than a flattened string.
• No user data. Nothing about you is stored. What the server does keep: a short-lived response cache and a small map of product ids it handed out, so an id can be resolved back to its seller list.
• Rate-aware by necessity. Torob does not throttle with a 429 - it answers a client that calls too fast with a bot challenge. Upstream calls are serialized with a 1.5s gap, and a challenge opens a circuit breaker instead of a retry storm.
• Undocumented upstream. Torob's public API can change without notice, which is exactly why the verify script exists.

Trust, verified

Don't take my word for it - check the live server yourself:

node scripts/verify-live.mjs   # needs Node.js 18+, nothing to install

It drives the real endpoint the way an MCP client does, paces its calls, and compares the version the live service reports against the newest release in this repo - so a deployment that lags these docs cannot stay quiet. The same script runs hourly in CI () - a red badge means the deployment drifted, because the endpoint checks never touch Torob's edge. A bot challenge is reported without failing the run: it is upstream's answer to a fast caller, not a broken deploy, and it clears on its own. See docs/architecture.md for the full path, including why a product id is not an address upstream and how a challenge is handled, and examples/python.py for a copy-paste client.

Run it yourself

npm install      # the one runtime dependency is a small Persian text helper
npm test         # builds, then runs every test in the repo
npm run dev      # the same Worker the live service runs, on your machine
npm run probe    # re-checks every upstream endpoint this server reads

Nothing to configure: no account, no key, no database, no bindings. npm run build && npx wrangler deploy puts your own copy on your own Cloudflare account.

Data source

Torob's public web API (undocumented, may change without notice). This project is not affiliated with or endorsed by Torob.

Status

Free public service on Cloudflare Workers, read-only and keyless. This hosted copy answers at most 20 /mcp calls a minute per client IP - a whole sweep of the tools takes about four, so a normal conversation never notices, while a script cannot use the service as an unmetered price API. Over the limit you get HTTP 429 with a retry-after header; running the server yourself has no limit at all. Separately, the pacing this server applies is to Torob, not to you, because Torob challenges a caller that goes too fast. See SECURITY.md.

License

MIT - see LICENSE. Security notes in SECURITY.md. Persian version in README_FA.md.