Digikala

Digikala MCP - shop intelligence for AI agents

A public MCP server that gives AI agents real data from Digikala - Iran's largest online marketplace: search, prices in Toman, discounts, ratings, sellers, reviews, deals and bestsellers. Read-only, no key needed.

Live endpoint: https://digikala-mcp.mmdju.workers.dev/mcp (Streamable HTTP)

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

Connect in 30 seconds

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

{
  "mcpServers": {
    "digikala": { "url": "https://digikala-mcp.mmdju.workers.dev/mcp" }
  }
}

Then just talk: "best Samsung phone under 100 million Toman", "is this laptop any good?", "what is on deal today?", "what is popular in Iran right now?".

No client at hand? The whole protocol is one POST - a real call:

curl -sS https://digikala-mcp.mmdju.workers.dev/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_digikala","arguments":{"query":"هدفون بی سیم","limit":2}}}'

And a real answer, trimmed to its bones (Toman, as JSON numbers):

{
  "query": "هدفون بی سیم",
  "returned": 2,
  "items": [
    { "id": 5112620, "title": "هدفون بی سیم مدل P47 5.0+EDR", "price_toman": 800000, "rating_stars": 3.7, "url": "https://www.digikala.com/product/dkp-5112620/" },
    { "id": 19019009, "title": "هدفون بلوتوثی مدل P9 V5.3 ...", "price_toman": 900000, "rating_stars": 3, "url": "https://www.digikala.com/product/dkp-19019009/" }
  ]
}

19 tools, grouped by the question

Find it

Know one product

Decide

What is hot

Using it well

• All prices are in Toman (1 Toman = 10 Rial). Prices, stock and discounts move constantly - always link the product URL so the user can confirm before buying.
• Start vague queries with digikala_suggest to get real search terms and a category_id; get brand_ids from search_filters or brand_lookup.
• Anything with a budget or the word "best" goes to find_best_value - plain search only sees one page. A brand word in query is not a filter - picks come from a price-sorted page - so pin the brand with brand_ids from brand_lookup.
• Digikala's search ORs its tokens: results that only partially match come back flagged low_confidence with the exact unmatched_terms, and clamped pages report page_clamped instead of silently correcting.
• Results are capped (default 10, max 30) to protect agent context; specs are capped at 60 attributes unless narrowed.
• Product counts are Digikala's own estimates and drift between pages - treat them as approximate.
• examples/sample-calls.md has nine copy-paste conversation flows; docs/tools.md is the full parameter reference.
• Persian queries are normalized with fa-text-utils (yeh/kaf folding, Persian digits, ZWNJ variants).

Reliability and limits

• Free public service on Cloudflare Workers. 20 requests per minute per IP on POST /mcp (HTTP 429 + retry-after; the counter is Cloudflare's, per data centre). A full agent session - handshake, a search, a few detail reads, one comparison - measures at roughly 15-20 POSTs, so ordinary use never comes close.
• A block is a wait, not a failure. Digikala's CDN challenges some regions; the server waits it out with backoff instead of retrying in a burst. Short blocks turn into real answers; a block that outlasts the window returns one honest message asking for a retry in 15-30 seconds.
• Polite pacing to Digikala: one shared gate across every instance - at most two upstream calls in flight, half a second apart.
• When a tag shelf will not answer, browse_tag falls back to a plain search for the shelf's name and labels the answer items_from_search: true - never a silent substitute.
• Nothing to sign up for. No accounts, no sessions, no API keys, and nothing about you stored. What the server does keep: a short-lived response cache (Cloudflare's Cache API - minutes for prices, hours for reads that barely move), Digikala's own bot-check cookie (10 minutes, so one solved challenge covers every instance in the same data centre), and a temporary failure log (tool, error kind, status, request path, product id - never your query, your IP or a title; rows are pruned after 30 days).
• Undocumented upstream. Digikala's public API can change without notice - this service tracks it and adapts, which is exactly why the verify script exists.

How it works

flowchart LR
    subgraph you [Your machine]
        agent[AI agent<br/>Cline / Cursor / Claude]
    end
    subgraph cf [Cloudflare Workers]
        worker[digikala-mcp<br/>read-only, no accounts]
    end
    dk[(Digikala public web API<br/>api.digikala.com)]

    agent -->|POST /mcp<br/>Streamable HTTP, no key| worker
    worker -->|HTTPS + polite pacing<br/>reads only| dk
    dk -->|compact JSON| worker
    worker -->|small cards<br/>toman, rating, URL| agent

One request in, one answer out - and nothing in that path stores who you are. The full picture is in docs/architecture.md.

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 checks the handshake, the live release against this repo's CHANGELOG, the tool list, a real search with a details read, and the two error paths. The same script runs hourly in CI () - if the endpoint or Digikala's API drifts, the badge goes red. examples/python.py is a copy-paste client (standard library only).

Data source

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

License

Showcase repository - docs, examples and the standalone live-verify script, no server source - see LICENSE. Security notes in SECURITY.md. Persian version in README_FA.md.

If this is useful, a star helps other builders find it.