torob-mcp

An MCP server for torob.com, Iran's price-comparison engine. Ask your assistant what something costs in Iran, who sells it cheapest, whether the price is good right now, and whether the shop can be trusted.

فارسی

Unofficial. This project is not affiliated with, endorsed by, or connected to Torob in any way. It is an independent client for the undocumented JSON endpoints torob.com's own website uses. Those can change or stop working without notice. All prices come from Torob and are reported as-is.

What it does

Fifteen tools covering search, prices, sellers, price history, physical shops and shop trust signals. Prices are normalized to Toman. Persian, English and Finglish queries all work — ayfon 13 finds what you'd expect.

You:  What's the cheapest iPhone 13 in Iran right now, and is it a good time to buy?

→ search_torob(query: "iPhone 13")
→ product_price_chart(product_id: …)   verdict: "great" — at the 25th percentile of 12 weeks
→ product_sellers(product_id: …)       cheapest reliable seller, ★5, 300-500 orders in 90 days

Related MCP server: Finland Shopping MCP

Install

Needs Node 22+.

Claude Code

claude mcp add torob -- npx -y torob-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

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

Cursor

.cursor/mcp.json in your project, or ~/.cursor/mcp.json globally:

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

Try it without installing

npx -y torob-mcp --help
npx -y @modelcontextprotocol/inspector npx -y torob-mcp

Tools

Example prompts

• «قیمت گوشی سامسونگ A55 چنده؟» — what does the Samsung A55 cost?

• "Best wireless headphones under 2 million Toman"

• "Is 113 million Toman a good price for a used iPhone 13 Pro right now?"

• "Which shops in Shiraz have this in stock?"

• "Compare the 128GB and 256GB versions"

• "Is this seller trustworthy? They're much cheaper than everyone else."

A good habit: ask it to link the product URL, because prices move constantly.

Remote mode

torob-mcp --http                      # 127.0.0.1:3000
torob-mcp --http --port 8080
torob-mcp --http --host 0.0.0.0       # requires TOROB_AUTH_TOKEN

• Binds loopback by default.

• A non-loopback bind requires TOROB_AUTH_TOKEN (16+ chars) unless you pass --insecure.

• Origin and Host are validated (DNS-rebinding protection); no wildcard CORS.

• GET /healthz makes no upstream call. POST /mcp is the transport.

Configuration

Everything is optional and validated at startup. See .env.example.

Deployment

⚠️ Torob blocks many cloud egress IPs. This is the single most likely reason a deployment fails. Cloudflare Workers and datacenter ranges (AWS, GCP, Azure, Hetzner, DigitalOcean, …) are frequently blocked or served a challenge page instead of JSON. The server reports this as a Blocked error rather than hanging.

An Iranian VPS, or a home connection in Iran, is the reliable option. Test first with pnpm test:live from the target host.

Full Docker, Iranian VPS, Fly.io and Railway recipes: docs/DEPLOY.md. Workers egress probe (Phase 5.0 gate): docs/WORKERS_EGRESS.md. Workers deploy guide: docs/DEPLOY_WORKERS.md.

Security model

Designed on the assumption that it runs on your machine and its output lands in an LLM's context window. Full detail in docs/THREAT_MODEL.md.

• Host allowlist. torob.com and api.torob.com only, re-checked on every redirect hop. Product ids are validated as UUIDs before a URL is ever built.

• Prompt-injection hygiene. Merchant-written titles and notes are third-party text. Control characters, bidi overrides and zero-width characters (except ZWNJ, meaningful in Persian) are stripped; fields are truncated. This reduces the risk, it does not eliminate it — the real protection is that this server is entirely read-only.

• Sponsored placements are labelled sponsored: true, never hidden.

• Shop profiles are an allowlist. ~15 of Torob's ~72 shop fields are emitted; the rest (billing internals, personal contact) are dropped.

• Supply chain. Four runtime dependencies, lockfile committed, install scripts disabled, npm provenance via OIDC, Actions pinned to SHAs, CodeQL + gitleaks + Scorecard + Trivy, SBOM per release, cosign-signed image.

What is sent to Torob

Only what a query needs: your search text (normalized), the ids and filters you asked for, page and size, our User-Agent, and unavoidably your IP address. One exception carries a derived deliver_city header: product_stores with a city argument.

No telemetry, no analytics, no disk persistence, no cookie jar. Full detail in docs/PRIVACY.md.

Development

pnpm install --frozen-lockfile
pnpm check          # oxlint + oxfmt + typecheck
pnpm test           # offline and deterministic
pnpm test:live      # opt-in, hits the real API
pnpm build
pnpm inspect        # MCP Inspector, interactive
pnpm inspect:cli    # Inspector CLI checks

Monorepo: packages/core is runtime-agnostic (no node:*; everything injected through Runtime); apps/node is the published package. See docs/ARCHITECTURE.md and CONTRIBUTING.md.

Docs

Wiki · Index · Endpoints · Architecture · Threat model · Privacy · Deploy · Dependencies · Security policy · Contributing

User-facing guides live in wiki/ (Getting started, Tools, Recipes, Deploy). Deep technical reference stays in docs/. Publish to the GitHub Wiki tab with pnpm wiki:publish after the first wiki page exists on GitHub.

License

MIT © Siamak Mokhtari