digikala-mcp 0.1.0__tar.gz

digikala_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: A tool failed or returned wrong data
+labels: [bug]
+body:
+  - type: input
+    id: tool
+    attributes:
+      label: Tool
+      description: Which tool, e.g. dk_find_cheapest
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: Arguments and result
+      description: The arguments the agent sent and the error or wrong output. Remove anything personal.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      description: e.g. the price shown on digikala.com for the same product
+  - type: input
+    id: client
+    attributes:
+      label: MCP client and OS
+      placeholder: Claude Desktop 1.x on Windows 11
+  - type: dropdown
+    id: network
+    attributes:
+      label: Network
+      options:
+        - Iranian IP, no VPN
+        - VPN or proxy
+        - DIGIKALA_MCP_PROXY set
+  - type: input
+    id: version
+    attributes:
+      label: digikala-mcp version
+      placeholder: "0.1.0"

digikala_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or idea
+    url: https://github.com/sepehr071/digikala-mcp/discussions
+    about: Ask how to use it or suggest a new tool

digikala_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly

digikala_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run pytest -q

digikala_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
+# pyproject.toml and server.json.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+      contents: write  # GitHub Release
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Check versions match the tag
+        run: |
+          TAG=${GITHUB_REF_NAME#v}
+          grep -q "^version = \"$TAG\"" pyproject.toml
+          test "$(jq -r .version server.json)" = "$TAG"
+          test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
+      - run: uv sync --locked && uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # MCP Registry login via GitHub OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Wait for PyPI to serve the new version
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf "https://pypi.org/pypi/digikala-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
+            sleep 10
+          done
+          exit 1
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

digikala_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/

digikala_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sepehr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

digikala_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.5
+Name: digikala-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Digikala: search products, compare sellers and prices, price history, reviews, deals.
+Project-URL: Homepage, https://github.com/sepehr071/digikala-mcp
+Project-URL: Issues, https://github.com/sepehr071/digikala-mcp/issues
+Author-email: Sepehr <sepehr@nextofx.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: digikala,e-commerce,iran,mcp,model-context-protocol,price-comparison,shopping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Description-Content-Type: text/markdown
+
+<!-- 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.
+
+[![PyPI](https://img.shields.io/pypi/v/digikala-mcp?color=2563eb)](https://pypi.org/project/digikala-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/digikala-mcp)](https://pypi.org/project/digikala-mcp/)
+[![CI](https://github.com/sepehr071/digikala-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/digikala-mcp/actions/workflows/ci.yml)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fdigikala--mcp-7c3aed)](https://registry.modelcontextprotocol.io/v0/servers?search=digikala-mcp)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/digikala-mcp/blob/main/LICENSE)
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=digikala&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJkaWdpa2FsYS1tY3AiXX0=)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_digikala--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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.
+
+<sub>Real tool output from 2026-10-03; prices change all the time. Prices are in Toman.</sub>
+
+## 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)