digikala-mcp: Digikala MCP server for AI agents

Let your AI agent shop around on Digikala (دیجی‌کالا).
An unofficial, read-only MCP server for Iran's largest online store: search products, compare every seller's offer,
check a product's price history, read reviews and Q&A, and catch today's Incredible Offers, all from Claude, Cursor or Copilot.

For AI agents · Quick start · What it can do · Tools · FAQ · فارسی

For AI agents

• What: unofficial MCP server for Digikala (digikala.com, Iran). Queries in Persian or English, prices in Toman.
• Install: uvx digikala-mcp or claude mcp add digikala -- uvx digikala-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional DIGIKALA_MCP_PROXY (HTTP proxy, e.g. with an Iranian exit if Digikala blocks yours).
• Access: read-only. No login, cart, checkout or payment, so no confirmation is needed before calling any tool.
• Tools: 23, all prefixed dk_. Start with dk_find_cheapest, dk_search, dk_best_for_budget, dk_deals. Typical sequence: dk_find_cheapest -> dk_product -> dk_price_history.
• Use when: finding, comparing or judging prices of products and sellers on Digikala, including the Fresh supermarket.
• Do not use when: the user wants to buy, or needs shipping cost (only calculated at checkout) or anything behind a login.
• Output: compact JSON. Prices in Toman, ratings 0-5 (null = not rated). Numeric product ids (the <id> of dkp-<id>) pass between tools.
• Machine-readable: server.json and the awesome-iran-mcp catalog (TOOLS.md, servers.json, llms.txt).

Why

Digikala lists the same phone many times: different colors, memory sizes, bundles and a dozen sellers per listing, with prices that move every day. Sorting by "cheapest" puts phone cases first. Finding the real cheapest offer, and whether today's price is a good one means a lot of clicking. An agent with digikala-mcp does it in three calls:

You: Cheapest Samsung Galaxy A07 on Digikala, and is now a good time to buy?

Agent: calls dk_find_cheapest(query="samsung a07") → dk_product(product_id=20109389) → dk_price_history(product_id=20109389)

Price	Model	Seller
42,503,600	Galaxy A07 64 GB / 4 GB	Digikala (same-day delivery in Tehran)
44,518,000	Galaxy A07 64 GB / 4 GB + 25 W charger	Sepahan Hamrah Yaghout
46,811,800	Galaxy A07 128 GB / 4 GB	Digikala

The 64 GB model is cheapest at 42,503,600, sold by Digikala itself; the next seller asks 42,918,000. But it's not a great moment: the black one sold for 34,499,000 yesterday and 33,200,000 at its lowest this month. Today's best offer is about 23% above yesterday's, so waiting may pay off.

_{Real tool output from 2026-10-03; prices change all the time. Prices are in Toman.}

What it can do

• 🔎 Search the whole catalogue in Persian or English, with price, brand, feature (OS, storage, ...), color, seller and fast-delivery filters; every result says whether its title really matches
• 💸 Find the real cheapest match, with accessories filtered out, and every seller's offer for a product
• 🏆 Best picks for a budget, ranked by a rating weighted by how many buyers rated it, with the reasoning shown
• 📋 Re-check a shortlist of up to 10 products in one call: price, cheapest offer, stock, distance from the 30-day low
• 📈 Judge a price with about 30 days of daily price history and the 30-day low
• 🗂️ Browse categories, brands, sellers and best sellers, sorted by price, sales, views, newest or buyers' pick
• ⭐ Check quality with reviews, pros/cons, buyer Q&A and seller reputation
• ⚡ Catch deals: Incredible Offers and supermarket (Digikala Fresh) discounts
• 🧾 Extras: spec comparison, installment plans, Digikala Plus shipping plans, live gold and coin prices
• 🔒 Read-only by design: no login, no cart, no orders, no payment

Quick start

You need uv. No API key or account.

claude mcp add digikala -- uvx digikala-mcp

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

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

Then just ask:

• "Cheapest AirPods-style earbuds under 3 million Toman with at least 4 stars?"
• "Compare the Galaxy A07 64 GB and 128 GB. Is the bigger one worth the difference?"
• "Is this seller reliable? CGDG9"
• ارزان‌ترین شیر کم‌چرب در سوپرمارکت دیجی‌کالا چند است؟

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  digikala-mcp  (runs on your machine)
      │
      │  HTTPS
      └──────▶  api.digikala.com   products, sellers, deals, Fresh supermarket

digikala-mcp runs locally and calls the same public endpoints the digikala.com web app uses. There's no hosted server in between, no API key, and nothing about you is sent anywhere else.

Tools

Product ids are the number in a digikala.com/product/dkp-<id>/ link. Every list returns compact product cards: id, title, brand, price, discount, stock, seller, rating, a photo URL (image) and the product link.

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

Good to know

• Prices are in Toman. The Digikala API answers in Rial; every tool divides by 10 so numbers match the website. Gold and coin prices are already Toman.
• Ratings are 0–5, like the site (the API's 0–100 divided by 20); null means not rated yet. Review stars are 1–5.
• Persian and English queries both work (گوشی سامسونگ, airpods pro). Category and brand codes are English slugs (mobile-phone, samsung).
• sort=cheapest on a text search shows accessories first; that's how Digikala ranks it. Use dk_find_cheapest for "cheapest X".
• Search always returns something, even for nonsense words (Digikala's search is semantic). dk_search marks each result match: all / some / none (with the missing words), and dk_find_cheapest and dk_best_for_budget keep only titles that contain every query word.
• Filters by feature: dk_filters(category_code="mobile-phone") lists ids like operating system → Android, then dk_category_products(attributes={2226: [19239]}) filters on them.
• The 30-day low ignores one-day dips. dk_shortlist compares today's price with the lowest price that held on two days in a row (low_30d), because Digikala's own 30-day low (lowest_one_day_30d, dk_product's lowest_price_30d) can be a single day of one color. dk_price_history gives both per color.
• Photos: cards carry image, dk_product an images list (max 4), both absolute https URLs taken from the API as-is. They end in ?x-oss-process=image/resize,m_lfit,h_300,w_300/quality,q_80, so they are 300 px JPEGs; drop that suffix for the original size.
• Prices move several times an hour on popular listings with many sellers; re-check right before buying.
• Answers are cached for 2 minutes, so an agent repeating a call doesn't hit Digikala again; prices can lag the site by that much.
• Groceries come from the supermarket store: dk_product shows its price, which can differ from the main-store price in search results.
• Shipping cost is only calculated at checkout (login). dk_product shows how each offer ships, and dk_plus_plans the free-shipping plans.

FAQ

npx @modelcontextprotocol/inspector uvx digikala-mcp

Configuration

فارسی: سرور MCP دیجی‌کالا

claude mcp add digikala -- uvx digikala-mcp

Development

git clone https://github.com/sepehr071/digikala-mcp && cd digikala-mcp
uv sync
uv run pytest            # offline, against recorded responses
uv run pytest -m live    # real API
uv run ruff check .

The live tests can also run on GitHub (Actions → Live → Run workflow). They are not scheduled: from GitHub's US runners Digikala times out on a few calls each run, while the same tests pass from an Iranian connection.

Tools live in src/digikala_mcp/catalog.py, product.py and services.py; each is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome, especially new tools and fixes for API changes.

Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions tests, publishes to PyPI and the MCP Registry, and creates the GitHub Release.

Related servers

• Technolife MCP server for electronics prices, with installment prices
• MasterKala MCP server for gadgets and phone accessories
• awesome-iran-mcp: catalog of all Iranian-service MCP servers

Disclaimer

Unofficial and not affiliated with or endorsed by Digikala. It uses the public endpoints of the digikala.com web app, which can change without notice. Please keep request rates reasonable.

License

MIT

If this saves you clicks, a star helps others find it.