masterkala-mcp: MasterKala MCP server for AI agents
Let your AI agent shop for gadgets on MasterKala (مسترکالا).
An unofficial, read-only MCP server for the Iranian gadget and mobile accessories shop: 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.
For AI agents · Quick start · What it can do · Tools · FAQ · فارسی
For AI agents
- What: unofficial MCP server for MasterKala (masterkala.com, Iran), a gadget and mobile accessories shop. Queries in Persian or English; prices in Toman.
- Install:
uvx masterkala-mcporclaude mcp add masterkala -- uvx masterkala-mcp. Transport: stdio. Needs uv (Python 3.10+). - Auth: none, no API key or account. Optional
MASTERKALA_MCP_PROXY(HTTP proxy, or a comma-separated list, for requests to masterkala.com). - Access: read-only. No login, cart, orders or posting reviews, so no confirmation is needed before calling any tool.
- Tools: 14, all prefixed
mk_. Start withmk_find_cheapest,mk_search,mk_deals,mk_browse. Typical sequence:mk_find_cheapest->mk_product->mk_shipping. - Use when: finding the cheapest orderable item, comparing specs, or checking stock and delivery on MasterKala.
- Do not use when: the user wants to buy. Delivery is an estimate for Tehran and "other cities by post", based on a default Tehran address.
- Output: compact JSON. Prices in Toman (
final_priceis what you pay), ratings 1-5 (null= no reviews). Numeric product ids pass between tools. - Machine-readable:
server.jsonand the awesome-iran-mcp catalog (TOOLS.md,servers.json,llms.txt).
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 Code
claude mcp add masterkala -- uvx masterkala-mcp
Claude Desktop
Settings → Developer → Edit Config, then add:
{
"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:
{
"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
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)
| Tool | What it does |
|---|---|
mk_search | Search by keyword: price, discount, stock, plus matching categories and tag pages |
mk_find_cheapest | Cheapest in-stock matches for a keyword, one flat list (accessories filtered out) |
mk_browse | A category, brand or tag sorted by price / stock / date, with price range and filters |
mk_filters | Brand, color and feature filter ids and the price range of a category, brand or tag |
mk_categories | Product categories and their ids |
mk_brands | Brands and their slugs |
mk_deals | Everything on the discount page, biggest discount first, with the time left |
📦 One product (5)
| Tool | What it does |
|---|---|
mk_product | Price, discount, stock status and count, colors, brand, category, rating, shops that have it |
mk_specs | Specification table of 1-4 products side by side |
mk_reviews | Customer reviews with star breakdown and the store's replies |
mk_shipping | Next delivery slot and fee for Tehran and other cities, same-day cut-off |
mk_branches | MasterKala's physical shops with address, phone and map location |
📝 Blog (2)
| Tool | What it does |
|---|---|
mk_blog_posts | Buying guides, comparisons and how-tos, newest first |
mk_blog_comments | Readers' questions on a post with the store writer's answers |
All 14 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_priceis what you pay,priceis before discount,discount_pctis 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_shippinggivesfree_shipping_from: nullfor them); below that, Tehran courier and post were 150,000 / 155,000 Toman on 2026-10-03. There is no address API, somk_shippingestimates for Tehran and "other cities by post". - Stock:
in_stockmeans orderable online now. Other statuses: ناموجود (sold out), به زودی (coming soon), موجود در شعب حضوری (only in the physical shops). - Images: every product has
image, an absolute https URL (328 px webp frommk_search,mk_find_cheapestandmk_browse; 240 px frommk_deals; the original jpg frommk_specs).mk_productgives a 600 pximageplus animageslist (up to 4). Null/empty fields are omitted from results,stock_statusonly appears when it is not "موجود" (in stock), and review / comment text is cut to 400 characters (blog threads keep 3 replies,more_repliescounts the rest). - Ratings are 1–5,
nullwhen nobody has reviewed the product yet. - Persian queries match best (
هندزفری,پاوربانک), but English brand and model names work too (xiaomi,Buds Pro).
FAQ
Is there a MasterKala API or MCP server for AI agents?
Yes: masterkala-mcp is an unofficial MCP server with 14 read-only tools for search, prices, specs, reviews,
delivery and deals. It calls the same public endpoints the masterkala.com website uses; no API key is needed.
How do I use MasterKala with Claude, Cursor or Copilot?
Add the server with claude mcp add masterkala -- uvx masterkala-mcp (or the matching config in
Quick start for Claude Desktop, Cursor and VS Code), then ask in plain language, in Persian or English.
Is it official, safe and free?
It is unofficial and not affiliated with MasterKala. It is read-only (no login, cart or payment), runs on your machine, and is free under the MIT license.
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 twice. If it still fails, check your internet connection. System proxy
variables are ignored on purpose; set MASTERKALA_MCP_PROXY if you need a proxy. If the shop shows a bot-check page, install the browser extra
(pip install "masterkala-mcp[browser]", then patchright install chromium) and the server clears it once.
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 masterkala-mcp
Configuration
| Variable | Default | Meaning |
|---|---|---|
MASTERKALA_MCP_PROXY | unset | HTTP proxy for every request, e.g. http://user:pass@host:port. A comma-separated list is used one at a time: the next proxy takes over when one is blocked or cannot connect |
فارسی: سرور MCP مسترکالا
masterkala-mcp یک سرور MCP غیررسمی و فقطخواندنی برای مسترکالا، فروشگاه اینترنتی گجت و لوازم جانبی موبایل در ایران، است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد در مسترکالا جستجو کند، ارزانترین کالای موجود را پیدا کند، مشخصات و نظرات را مقایسه کند و زمان و هزینه ارسال و تخفیفهای روز را ببیند.
- فقط خواندنی است: وارد حساب نمیشود، سبد خرید نمیسازد، سفارش ثبت نمیکند و نظر نمیفرستد.
- قیمتها به تومان است و کاور و قاب را از نتایج «ارزانترین» جدا میکند.
- روی سیستم خود شما اجرا میشود و به هیچ سرور واسطی داده نمیفرستد.
نصب در Claude Code:
claude mcp add masterkala -- uvx masterkala-mcp
بعد بپرسید: «ارزانترین هندزفری بلوتوث بین ۳ تا ۵ میلیون تومان کدام است و کی به تهران میرسد؟»
Development
git clone https://github.com/sepehr071/masterkala-mcp && cd masterkala-mcp
uv sync
uv run python -m pytest # offline, against recorded responses
uv run python -m 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.
Related servers
- Digikala MCP server for Iran's largest online store
- Technolife MCP server for electronics prices, with installment prices
- awesome-iran-mcp: catalog of all Iranian-service MCP servers
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
If this saves you clicks, a star helps others find it.