MasterKala

io.github.sepehr071v0.1.0Updated Oct 3, 2026

Unofficial read-only MasterKala: search gadgets, compare prices and specs, stock, delivery, deals.

VerifiedSTDIODesktop onlyWeb Search & ScrapingBusiness & Commerce

Overview

AI-generated overview

Read-only search of the MasterKala gadget store: prices, specs, stock, delivery slots and deals, without logging in or ordering.

What it does
Wraps the public masterkala.com endpoints in read-only tools: keyword search, cheapest in-stock match, browsing categories, brands and tags with filters, and the discount page. For a single product it returns price, discount, stock, colors, ratings, reviews, a side-by-side spec table, delivery slots and fees, and physical branch details. Two blog tools fetch buying guides and reader comments. All tools are annotated read-only and return compact JSON.
When to use it
Useful when you want an assistant to compare gadget prices and specs, check whether an item is orderable and when it would arrive, or catch current discounts on MasterKala. It fits price-hunting and product-research questions rather than anything transactional.
Requirements
Runs locally over stdio; needs uv (uvx masterkala-mcp) or pip install masterkala-mcp. No account or API key. Internet access to masterkala.com is required; an optional MASTERKALA_MCP_PROXY variable sets an HTTP proxy, since system proxy settings are ignored. Desktop only.
Before you install
Unofficial and unaffiliated with MasterKala; it relies on public site endpoints that can change without notice. Read-only by design: no login, cart, order, payment or review posting. Prices are in Toman and change often, and shipping is estimated rather than address-based. If you set MASTERKALA_MCP_PROXY, credentials in that proxy URL are passed to the proxy.

Installation

In SourceWeft

  1. Open MasterKala in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

🎧 masterkala-mcp

Let your AI agent shop for gadgets on MasterKala.
Search earbuds, chargers, power banks and smart watches, compare real prices and specs,
read reviews, check stock and delivery dates, and catch today's discounts, all from Claude, Cursor or Copilot.

[PyPI] [Python] [CI] [MCP Registry] [License: MIT]

[Install in Cursor] [Install in VS Code]

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

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)

TotalProductPriceShipping
4,338,000پاوربانک 10000 شیائومی گلوریمی Glorimi LightCore 22.5W4,188,000 (5% off)150,000, Saturday 15:00-18:00
5,291,000پاوربانک فوق نازک مگنتی 5000 Glorimi FitCore Mag 20W5,291,000 (4% off)free (over 5M)
5,401,000پاوربانک 20000 شیائومی گلوریمی Glorimi LightCore 22.5W5,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 Code
bash
claude mcp add masterkala -- uvx masterkala-mcp
Claude Desktop

Settings → Developer → Edit Config, then add:

json
{  "mcpServers": {    "masterkala": { "command": "uvx", "args": ["masterkala-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:

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

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

text
  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

🔎 Find products (7)
ToolWhat it does
mk_searchSearch by keyword: price, discount, stock, plus matching categories and tag pages
mk_find_cheapestCheapest in-stock matches for a keyword, one flat list (accessories filtered out)
mk_browseA category, brand or tag sorted by price / stock / date, with price range and filters
mk_filtersBrand, color and feature filter ids and the price range of a category, brand or tag
mk_categoriesProduct categories and their ids
mk_brandsBrands and their slugs
mk_dealsEverything on the discount page, biggest discount first, with the time left
📦 One product (5)
ToolWhat it does
mk_productPrice, discount, stock status and count, colors, brand, category, rating, shops that have it
mk_specsSpecification table of 1-4 products side by side
mk_reviewsCustomer reviews with star breakdown and the store's replies
mk_shippingNext delivery slot and fee for Tehran and other cities, same-day cut-off
mk_branchesMasterKala's physical shops with address, phone and map location
📝 Blog (2)
ToolWhat it does
mk_blog_postsBuying guides, comparisons and how-tos, newest first
mk_blog_commentsReaders' questions on a post with the store writer's answers

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

Can it place an order for me?

No, and that's deliberate. It has no login and never touches the cart, order, payment, wishlist or review endpoints. The agent finds the best option; you buy it on masterkala.com.

Why does mk_find_cheapest skip some items?

It keeps only items you can order online now, whose title contains every word of your query, and drops cases, covers and screen protectors unless you ask for them (include_accessories: true, or a query like "کاور ..."). It scans the first 500 results by default (in-stock items come first); complete: false in the reply means more in-stock items lie past that, so raise scan (up to 1500). mk_search shows everything.

I get "Could not reach masterkala.com"

The server retries a dropped connection once. If it still fails, check your internet connection. System proxy variables are ignored on purpose; set MASTERKALA_MCP_PROXY if you need a proxy.

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?
bash
npx @modelcontextprotocol/inspector uvx masterkala-mcp

Configuration

VariableDefaultMeaning
MASTERKALA_MCP_PROXYunsetHTTP proxy for every request, e.g. http://user:pass@host:port

فارسی

masterkala-mcp به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در مسترکالا جستجو کند، ارزان‌ترین کالای موجود را پیدا کند، مشخصات و نظرات را مقایسه کند و زمان و هزینه ارسال و تخفیف‌های روز را ببیند.

  • فقط خواندنی است: وارد حساب نمی‌شود، سبد خرید نمی‌سازد، سفارش ثبت نمی‌کند و نظر نمی‌فرستد.
  • قیمت‌ها به تومان است و کاور و قاب را از نتایج «ارزان‌ترین» جدا می‌کند.
  • روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.

نصب در Claude Code:

bash
claude mcp add masterkala -- uvx masterkala-mcp

بعد بپرسید: «ارزان‌ترین هندزفری بلوتوث بین ۳ تا ۵ میلیون تومان کدام است و کی به تهران می‌رسد؟»

Development

bash
git clone https://github.com/sepehr071/masterkala-mcp && cd masterkala-mcpuv syncuv run pytest            # offline, against recorded responsesuv run pytest -m live    # real masterkala.comuv 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

Source: README.md at commit f3bceab

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.0LatestOct 3, 2026