---

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 Code

claude mcp add digikala -- uvx digikala-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

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

Cursor

Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json.

VS Code (Copilot agent mode)

Click Install in VS Code above, or add to .vscode/mcp.json:

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

Anything else

It's a standard stdio MCP server: run uvx digikala-mcp, or pip install digikala-mcp and run 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.

🔎 Find products (12)

Tool	What it does
dk_search	Search by words with sort, price, brand, feature, color and seller filters; flags loose title matches
dk_find_cheapest	Cheapest in-stock real matches for a query, accessories dropped, one list
dk_best_for_budget	Best-rated real matches under a budget, rating weighted by number of ratings
dk_suggest	Autocomplete: better keywords, category codes and brand ids
dk_filters	Filter options of a category or search: features (OS, storage, ...), colors, brands, sellers, price range
dk_categories	Find category codes and main-category ids
dk_category_products	Browse a category with sort and the same filters, optionally one brand
dk_brand_products	Browse a brand's products
dk_seller	A seller's rating, on-time shipping, cancellations, returns and products
dk_deals	Incredible Offers or supermarket deals, biggest discount first
dk_best_sellers	Current best sellers, overall or per main category
dk_fresh_search	Search or browse Digikala Fresh, the supermarket

📦 Products (8)

Tool	What it does
dk_product	Price, stock, specs and every seller's offer (color, warranty, shipping), cheapest first
dk_shortlist	Re-price up to 10 products at once: price, cheapest offer, stock, rating, distance from the 30-day low
dk_price_history	About 30 days of daily prices per color, with low and high
dk_reviews	Customer reviews with stars, pros/cons and verified-buyer flag
dk_questions	Customer questions with their top answers
dk_similar	Similar products, e.g. cheaper alternatives
dk_compare	2-4 products side by side: the specs that differ, plus the shared ones
dk_installments	Digipay credit-line offers for a product (credit amount, monthly repayment, months)

🧾 Other (3)

Tool	What it does
dk_plus_plans	Digikala Plus membership plans (free shipments) and benefits
dk_gold_prices	Live 18k gold price per gram (daily and ~3-month change) and gold coin prices
dk_location	Address → coordinates, or coordinates → address with Digikala city/province ids

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

Do I need an Iranian IP?

Usually not: in testing the API answered from a foreign (Turkish) exit. If every tool fails with
"refused the request (HTTP 403)", set DIGIKALA_MCP_PROXY to an HTTP proxy with an Iranian exit. (A 403 from just
one call usually means an unknown category or brand code.) Normal system
proxy variables are ignored on purpose.

Can it buy something for me?

No, and that's deliberate. It has no login and never calls the cart, checkout, payment, or review/question
posting endpoints; it only reads public data. The agent finds the best option; you tap buy on the site.

A product shows in_stock: false and no price

Digikala lists products that are out of stock, coming soon or discontinued. They have no current offer, so there's
no price. Searches use in_stock_only: true by default.

Claude Desktop says uvx is not found

Use the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.

How do I debug what the agent sees?

npx @modelcontextprotocol/inspector uvx digikala-mcp

Configuration

Variable	Default	Meaning
DIGIKALA_MCP_PROXY	unset	HTTP proxy for every request, e.g. http://user:pass@host:port

فارسی

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.

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