Why

MasterKala lists thousands of accessories, and a search for "power bank" mixes real power banks with silicone covers, out-of-stock items and things sold only in its shops. Finding the cheapest one you can actually order, and what it costs delivered, means paging through results and opening product pages. An agent with masterkala-mcp does that in seconds:

You: Cheapest Xiaomi power bank I can order now, delivered in Tehran?

Agent: calls mk_find_cheapest(query="پاوربانک شیائومی") → mk_shipping(product_id=26935)

Total	Product	Price	Shipping
4,338,000	پاوربانک 10000 شیائومی گلوریمی Glorimi LightCore 22.5W	4,188,000 (5% off)	150,000, Saturday 15:00-18:00
5,291,000	پاوربانک فوق نازک مگنتی 5000 Glorimi FitCore Mag 20W	5,291,000 (4% off)	free (over 5M)
5,401,000	پاوربانک 20000 شیائومی گلوریمی Glorimi LightCore 22.5W	5,401,000 (6% off)	free (over 5M)

The 10,000 mAh LightCore is cheapest even with the 150,000 courier fee. The 20,000 mAh LightCore ships free and costs 1,063,000 more for twice the capacity. Want me to compare their specs with mk_specs?

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

What it can do

• 🔎 Search products by name in Persian or English, with price, discount and stock
• 💸 Find the cheapest in-stock match, with cases and covers filtered out
• 🗂️ Browse any category, brand or tag sorted by price, stock or date, with price range and brand/color filters
• 📋 Read full product details: colors, stock count, specs, side-by-side comparison, reviews
• 🚚 Check delivery: next Tehran courier slot, post to other cities, shipping fee, same-day cut-off
• ⚡ Catch deals on the discount page, plus buying guides from the MasterKala blog
• 🔒 Read-only by design: no login, no cart, no orders, no reviews posted

Quick start

You need uv. No API key or account.

claude mcp add masterkala -- uvx masterkala-mcp

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

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

Then just ask:

• "Cheapest Bluetooth earbuds between 3 and 5 million Toman, and which one has the best reviews?"
• "Compare the specs of the Green Lion Ocean and the Awei T66."
• "Is the blue CMF Buds Pro 2 in stock? When would it reach Tehran?"
• بهترین تخفیف‌های امروز مسترکالا روی پاوربانک چیه؟

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  masterkala-mcp  (runs on your machine)
      │
      │  HTTPS
      └──────▶  masterkala.com   JSON API, listing fragments, product pages

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

Tools

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. final_price is what you pay, price is before discount, discount_pct is a whole percent. The site's structured data is in Rial; the server converts it.
• Shipping is free from 5,000,000 Toman per order for most items (bulky goods such as large speakers never ship free; mk_shipping gives free_shipping_from: null for them); below that, Tehran courier and post were 150,000 / 155,000 Toman on 2026-10-03. There is no address API, so mk_shipping estimates for Tehran and "other cities by post".
• Stock: in_stock means orderable online now. Other statuses: ناموجود (sold out), به زودی (coming soon), موجود در شعب حضوری (only in the physical shops).
• Ratings are 1–5, null when nobody has reviewed the product yet.
• Persian queries match best (هندزفری, پاوربانک), but English brand and model names work too (xiaomi, Buds Pro).

FAQ

npx @modelcontextprotocol/inspector uvx masterkala-mcp

Configuration

فارسی

claude mcp add masterkala -- uvx masterkala-mcp

Development

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

Tools live in src/masterkala_mcp/catalog.py, product.py and blog.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 site 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 MasterKala. It uses the public endpoints of the masterkala.com website, which can change without notice. Please keep request rates reasonable.

License

MIT