Digikala MCP - Shop intelligence for AI agents

A public MCP server that gives AI agents real Digikala knowledge: 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, stateless)

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

Connect in 30 seconds

Any 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 20 million Toman”, “is this laptop any good?”, “what is on deal today?”, “what is popular in Iran right now?”.

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

16 tools

Notes for agent builders:

• 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.
• Anything with a budget or the word “best” goes to find_best_value - plain search only sees one page.
• Product counts are Digikala’s own estimates and drift between pages - treat them as approximate.
• Digikala’s search ORs its tokens - results that only partially match a query come back flagged low_confidence (with the exact unmatched_terms), and silently clamped pages report page_clamped.
• Results are capped (default 10, max 30) to protect agent context. Specs are capped at 60 attributes unless narrowed.
• See examples/sample-calls.md for eight copy-paste conversation flows, and docs/tools.md for the full parameter reference.
• Persian queries are normalized with fa-text-utils (yeh/kaf folding, Persian digits, ZWNJ variants) - the same tiny helpers, published separately.

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 agentCline / Cursor / Claude]
    end
    subgraph cf [Cloudflare Workers]
        worker[digikala-mcpstateless, no database]
    end
    dk[(Digikala public web APIapi.digikala.com)]

    agent -->|POST /mcpStreamable HTTP, no key| worker
    worker -->|HTTPS + polite pacingreads only| dk
    dk -->|compact JSON| worker
    worker -->|small cardstoman, rating, URL| agent

What this means:

• Stateless. Every request stands alone - no sessions, no accounts, nothing to log in to.
• Read-only. All 16 tools carry readOnlyHint. Nothing here can change, delete or order anything.
• No user data. Nothing about you is stored. What the server does keep: a short-lived response cache (a few minutes) and Digikala’s own CDN bot-check cookie (10 minutes), so one solved challenge covers every instance in the same data centre. Prices, stock and discounts are re-read from Digikala every time the cache expires.
• Rate-limit aware. Requests go out half a second apart. When Digikala pushes back - its cookie challenge or a 429 - the server waits it out with exponential backoff and a bit of randomness, instead of retrying in a burst.
• Undocumented upstream. Digikala’s public API can change without notice - this service tracks it and adapts, 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 lists all 16 tools over Streamable HTTP, runs a search + details read + error paths, and asserts the honest-data contract. The same script runs hourly in CI () - if the endpoint or Digikala’s API drifts, the badge goes red. See docs/architecture.md for how a question becomes an answer, and examples/python.py for a copy-paste client.

Data source

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

Status

Free public service on Cloudflare Workers. 60 requests per minute per IP on POST /mcp (HTTP 429 + retry-after when exceeded; the counter is Cloudflare’s rate limiting service, per data centre). A normal agent session never comes close - the limit only stops flood abuse. What the server still paces is its own calls to Digikala: half a second apart, with backoff when Digikala pushes back, so ordinary agent use never looks like a flood.

License

Showcase repository (docs only, no source published) - see LICENSE. Security notes in SECURITY.md. Persian version in README_FA.md.