digikala-mcp

<!-- mcp-name: io.github.sepehr071/digikala-mcp --> <div align="center"> # 🛍️ digikala-mcp **Let your AI agent shop around on Digikala.**<br> Search Iran's largest online store, compare every seller's offer, check a product's price history,<br> read reviews and Q&A, and catch today's Incredible Offers, all from Claude, Cursor or Copilot. [](https://pypi.org/project/digikala-mcp/) [](https://pypi.org/project/digikala-mcp/) [](https://github.com/sepehr071/digikala-mcp/actions/workflows/ci.yml) [](https://registry.modelcontextprotocol.io/v0/servers?search=digikala-mcp) [](https://github.com/sepehr071/digikala-mcp/blob/main/LICENSE) [](https://cursor.com/en/install-mcp?name=digikala&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJkaWdpa2FsYS1tY3AiXX0=) [](https://vscode.dev/redirect/mcp/install?name=digikala&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22digikala-mcp%22%5D%7D) [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی) </div> --- ## 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, and the 30-day low was 28,373,600. 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 range, brand and in-stock filters - 💸 **Find the real cheapest match**, with accessories filtered out, and every seller's offer for a product - 📈 **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](https://docs.astral.sh/uv/getting-started/installation/). No API key or account. <details open> <summary><b>Claude Code</b></summary> ```bash claude mcp add digikala -- uvx digikala-mcp ``` </details> <details> <summary><b>Claude Desktop</b></summary> Settings → Developer → Edit Config, then add: ```json { "mcpServers": { "digikala": { "command": "uvx", "args": ["digikala-mcp"] } } } ``` </details> <details> <summary><b>Cursor</b></summary> Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`. </details> <details> <summary><b>VS Code (Copilot agent mode)</b></summary> Click **Install in VS Code** above, or add to `.vscode/mcp.json`: ```json { "servers": { "digikala": { "type": "stdio", "command": "uvx", "args": ["digikala-mcp"] } } } ``` </details> <details> <summary><b>Anything else</b></summary> It's a standard stdio MCP server: run `uvx digikala-mcp`, or `pip install digikala-mcp` and run `digikala-mcp`. </details> 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" - <span dir="rtl">ارزان&zwnj;ترین شیر کم&zwnj;چرب در سوپرمارکت دیجی&zwnj;کالا چند است؟</span> ## How it works ```text 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 and the product link. <details open> <summary><b>🔎 Find products</b> (10)</summary> | Tool | What it does | |---|---| | `dk_search` | Search by words with sort, price range, brand and in-stock filters | | `dk_find_cheapest` | Cheapest in-stock real matches for a query, accessories dropped, one list | | `dk_suggest` | Autocomplete: better keywords, category codes and brand ids | | `dk_categories` | Find category codes and main-category ids | | `dk_category_products` | Browse a category with sort and 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 | </details> <details open> <summary><b>📦 One product</b> (7)</summary> | Tool | What it does | |---|---| | `dk_product` | Price, stock, specs and every seller's offer (color, warranty, shipping), cheapest first | | `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) | </details> <details open> <summary><b>🧾 Other</b> (3)</summary> | 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 | </details> All 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_find_cheapest` keeps only titles that contain every query word. - **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 <details> <summary><b>Do I need an Iranian IP?</b></summary> 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. </details> <details> <summary><b>Can it buy something for me?</b></summary> 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. </details> <details> <summary><b>A product shows <code>in_stock: false</code> and no price</b></summary> 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. </details> <details> <summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary> Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`. </details> <details> <summary><b>How do I debug what the agent sees?</b></summary> ```bash npx @modelcontextprotocol/inspector uvx digikala-mcp ``` </details> ## Configuration | Variable | Default | Meaning | |---|---|---| | `DIGIKALA_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port` | ## فارسی <div dir="rtl"> **digikala-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می&zwnj;دهد در دیجی&zwnj;کالا جستجو کند، قیمت همه فروشندگان یک کالا را مقایسه کند، تاریخچه قیمت، نظرات و پرسش&zwnj;وپاسخ&zwnj;ها را بخواند و پیشنهادهای شگفت&zwnj;انگیز را پیدا کند. - فقط خواندنی است: وارد حساب نمی&zwnj;شود، سبد خرید نمی&zwnj;سازد و سفارش ثبت نمی&zwnj;کند. - همه قیمت&zwnj;ها به تومان است و امتیازها مثل سایت از ۵. - روی سیستم خود شما اجرا می&zwnj;شود و به هیچ سرور واسطی داده نمی&zwnj;فرستد. **نصب در Claude Code:** </div> ```bash claude mcp add digikala -- uvx digikala-mcp ``` <div dir="rtl"> بعد بپرسید: «ارزان&zwnj;ترین گوشی سامسونگ A07 کدام است و الان قیمتش خوب است؟» </div> ## Development ```bash 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 . ``` 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](https://registry.modelcontextprotocol.io), 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](https://github.com/sepehr071/digikala-mcp/blob/main/LICENSE)