masterkala-mcp
A read-only MasterKala MCP server for product research, price/spec comparison, stock, reviews, delivery estimates, deals, blog guides, and branch info.
Search MasterKala products by Persian or English keyword with price, discount, and stock.
Find the cheapest in-stock products for a query, with accessories filtered out by default.
Browse categories, brands, or tags with sorting, price range, and brand/color/feature filters.
Get category IDs, brand slugs, and available filter options.
View full product details: price, discount, stock, colors, rating, category, and branches.
Compare specifications for up to 4 products side by side.
Read customer reviews, star breakdowns, and store replies.
Estimate Tehran courier/post delivery fees and next delivery slots.
See current discount-page deals, biggest discount first.
Read blog buying guides, comparisons, how-tos, and reader Q&A.
Find MasterKala physical branch addresses, phones, and map locations.
Cannot log in, manage a cart, place orders, pay, or post reviews.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@masterkala-mcp Cheapest Xiaomi power bank I can order now, delivered to Tehran?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
masterkala-mcp: MasterKala MCP server for AI agents
Let your AI agent shop for gadgets on MasterKala (مسترکالا). An unofficial, read-only MCP server for MasterKala, 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 · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development · Related servers
For AI agents
What: unofficial MCP server (model context protocol) for MasterKala (masterkala.com, Iran), a gadget and mobile accessories shop that sells its own stock. 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 URL, or a comma-separated list, for requests to masterkala.com); system proxy settings are ignored.Access: read-only. It cannot log in, use the cart, place orders or post 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: the user wants the cheapest orderable item, a spec or price comparison, reviews, stock, a delivery estimate, current discounts or a MasterKala buying guide.
Do not use when: the user wants to buy (the agent finds the item, the user orders on masterkala.com), needs another shop, or needs delivery to a specific address: 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 iran-mcp catalog (TOOLS.md,servers.json,llms.txt).
Related MCP server: cross-shop
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 and readers' questions from the MasterKala blog
Find a shop: the physical MasterKala branches in Tehran with address, phone and map location
Read-only by design: no login, no cart, no orders, no reviews posted
Example prompts:
"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?"
"What are today's biggest discounts on smart watches?"
"Where are MasterKala's physical shops in Tehran?"
بهترین تخفیف‌های امروز مسترکالا روی پاوربانک چیه؟
ارزان‌ترین هندزفری بلوتوث موجود را پیدا کن و بگو کی به تهران می‌رسد.
مشخصات دو ساعت هوشمند را کنار هم مقایسه کن و نظر خریداران را بگو.
Quick start
You need uv. No API key or account.
claude mcp add masterkala -- uvx masterkala-mcpSettings → Developer → Edit Config, then add:
{
"mcpServers": {
"masterkala": { "command": "uvx", "args": ["masterkala-mcp"] }
}
}Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code above, or add to .vscode/mcp.json:
{
"servers": {
"masterkala": { "type": "stdio", "command": "uvx", "args": ["masterkala-mcp"] }
}
}codex mcp add masterkala -- uvx masterkala-mcpOr in ~/.codex/config.toml:
[mcp_servers.masterkala]
command = "uvx"
args = ["masterkala-mcp"]Add to ~/.gemini/settings.json:
{
"mcpServers": {
"masterkala": { "command": "uvx", "args": ["masterkala-mcp"] }
}
}Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It's a standard stdio MCP server: run uvx masterkala-mcp, or pip install masterkala-mcp and run masterkala-mcp.
Tools
All tools are prefixed mk_. Product ids are numbers like 24855; category ids come from mk_categories, brand slugs from mk_brands.
Tool | What it does |
| Search by keyword: price, discount, stock, plus matching categories and tag pages |
| Cheapest in-stock matches for a keyword, one flat list sorted by payable price (accessories filtered out) |
| A category, brand or tag sorted by price / stock / date, with price range and filters |
| Brand, color and feature filter ids and the price range of a category, brand or tag |
| Product categories and their ids (about 100 main categories) |
| Brands and their slugs (about 135) |
| Everything on the discount page, biggest discount first, with the time left |
Tool | What it does |
| Price, discount, stock status and count, colors, brand, category, rating, shops that have it |
| Specification table of 1-4 products side by side |
| Customer reviews with star breakdown and the store's replies |
| Next delivery slot and fee for Tehran and other cities, same-day cut-off |
| MasterKala's physical shops in Tehran with address, phone and map location |
Tool | What it does |
| Buying guides, comparisons and how-tos, newest first |
| Readers' questions on a post with the store writer's answers |
All 14 tools are annotated readOnlyHint: true and return compact JSON, so they don't flood the agent's context.
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 pagesmasterkala-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.
Requests go out through a Chrome-impersonating HTTP client, at most 2 at a time with a short random delay, and a dropped
connection is retried up to twice. The category and brand lists are cached for an hour. Review, comment and description
text is treated as untrusted site content and cut to a short length.
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).Keyword listings ignore sort. For a keyword use
mk_searchormk_find_cheapest; usemk_browsewith a category id, brand slug or tag id when you need sorting, a price range or filters.Rate limits: the site's robots.txt disallows its API paths for crawlers, so keep request rates low (about one per second). The server already limits concurrency and adds a short delay.
What it does not do: no login, cart, orders, payment, wishlist or review posting; no other shops; no delivery to a specific address.
Proxy: set
MASTERKALA_MCP_PROXYif you need one (see Configuration).
FAQ
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.
Add the server with claude mcp add masterkala -- uvx masterkala-mcp (or the matching config in
Quick start for Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI and Windsurf), then ask in plain language, in Persian or English.
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.
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.
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.
Toman. final_price is what the customer pays after discount. The site's structured data uses Rial, and the server converts it.
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.
Use the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
npx @modelcontextprotocol/inspector uvx masterkala-mcpConfiguration
Variable | Default | Meaning |
| unset | Optional HTTP proxy URL for every request to masterkala.com, e.g. |
فارسی: سرور MCP مسترکالا
masterkala-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای مسترکالا، فروشگاه اینترنتی گجت و لوازم جانبی موبایل در ایران، است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در مسترکالا جستجو کند، ارزان‌ترین کالای موجود را پیدا کند، مشخصات و نظرات را مقایسه کند و زمان و هزینه ارسال و تخفیف‌های روز را ببیند.
چه کارهایی می‌کند
جستجوی هندزفری، پاوربانک، شارژر، کابل، ساعت هوشمند و اسپیکر با قیمت، تخفیف و وضعیت موجودی.
پیدا کردن ارزان‌ترین کالای موجود برای یک عبارت، بدون کاور و قاب.
مرور دسته‌ها، برندها و برچسب‌ها با مرتب‌سازی و فیلتر قیمت، برند و رنگ.
مشخصات فنی، مقایسه تا ۴ کالا کنار هم، و نظرات خریداران با پاسخ فروشگاه.
زمان و هزینه ارسال به تهران و شهرهای دیگر (پست)، و شعب حضوری مسترکالا در تهران.
تخفیف‌های روز و مقاله‌های راهنمای خرید وبلاگ.
نکته‌ها
فقط خواندنی است: وارد حساب نمی‌شود، سبد خرید نمی‌سازد، سفارش ثبت نمی‌کند و نظر نمی‌فرستد. خرید را خودتان در سایت انجام می‌دهید.
قیمت‌ها به تومان است و کاور و قاب را از نتایج «ارزان‌ترین» جدا می‌کند.
هزینه و زمان ارسال برآورد است، برای تهران و «سایر شهرها با پست»؛ آدرس دقیق پشتیبانی نمی‌شود.
کلید API لازم نیست؛ روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.
اگر لازم بود، متغیر
MASTERKALA_MCP_PROXYرا روی یک پراکسی HTTP بگذارید.
نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add masterkala -- uvx masterkala-mcpدر Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسش‌ها
«ارزان‌ترین هندزفری بلوتوث بین ۳ تا ۵ میلیون تومان کدام است و کی به تهران می‌رسد؟»
«بهترین تخفیف‌های امروز مسترکالا روی پاوربانک چیه؟»
«ارزان‌ترین پاوربانک شیائومی موجود را پیدا کن.»
«مشخصات دو ساعت هوشمند را مقایسه کن.»
«شعب مسترکالا در تهران کجاست؟»
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
iran-mcp: catalog of all Iranian-service MCP servers
Digikala MCP server for Iran's largest online store
Technolife MCP server for electronics prices, with installment prices
Torob MCP server for comparing prices across Iranian shops
Okala MCP server for online grocery shopping
Banimode MCP server for fashion
Listed on mcpfarsi.ir, the Persian MCP marketplace
Disclaimer
Unofficial and not affiliated with or endorsed by MasterKala. It is read-only and uses the public endpoints of the masterkala.com website, which can change without notice. Please keep request rates reasonable.
Author
Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.
License
If this saves you clicks, a star helps others find it.
Available Tools
14 toolsmk_blog_commentsBlog post commentsBRead-only
Read the comments of a blog post as threads, with the store writer's answers as replies.
Useful as a support FAQ: many posts hold readers' product questions answered by MasterKala.
Inputs: post_id (required), limit, full_text.
mk_blog_postsBlog posts and buying guidesARead-only
List MasterKala blog posts (buying guides, comparisons, how-tos), newest first, with links.
Use for which-type-to-choose or how-to questions. Readers' Q&A: mk_blog_comments.
Inputs: page, limit, category.
mk_branchesPhysical branchesARead-only
List MasterKala's physical shops in Tehran with address, phone and map location.
mk_product's branches says which shops have a given product.
Inputs: no named parameters.
mk_brandsList brandsARead-only
List the brands MasterKala sells with their slugs (about 135).
Use to get the brand slug for mk_browse / mk_filters.
Inputs: query.
mk_browseBrowse a category or brandARead-only
List the products of a category, brand or tag with sorting, price range and filters.
Pass exactly one of category_id / brand / tag_id. No keyword search here: mk_search.
Inputs: page, sort, brand, limit, +5 more.
mk_categoriesList categoriesARead-only
List MasterKala's product categories with their ids (about 100).
Use to get a category_id for mk_browse / mk_filters.
Inputs: query.
mk_dealsCurrent dealsARead-only
List products on MasterKala's discount page, biggest discount first.
ends_in_seconds = time left in the current offer period.
Inputs: limit.
mk_filtersFilters of a category or brandARead-only
List the filters of a category, brand or tag page with their ids, and its price range.
Use before mk_browse; options map filter id -> name. Non-brand groups are cut to 40
(omitted = rest): pass group for all. max_price in Toman.
Inputs: brand, group, tag_id, category_id.
mk_find_cheapestFind cheapest productARead-only
Find the cheapest in-stock products for a keyword, one flat list sorted by final_price.
Use for the lowest price of X. free_shipping = reaches 5,000,000 Toman (bulky items never).
complete=false: more in-stock items past scanned; raise scan.
Inputs: query (required), scan, limit, match_all_words, +1 more.
mk_productProduct detailsARead-only
Get one product's full record: price (Toman), stock count, colors, category path, rating, branches.
Use after mk_search / mk_browse. Specs: mk_specs. Reviews: mk_reviews. Delivery: mk_shipping.
Inputs: product_id (required), full_text.
mk_reviewsProduct reviewsARead-only
Read customer reviews of a product (newest first) with store replies and the star breakdown.
average and star_counts cover all reviews; count matches stars.
Inputs: product_id (required), limit, stars, full_text.
mk_searchSearch productsARead-only
Search MasterKala products by keyword: price, discount and stock of each match.
Use first for "price of X". In-stock first. Also returns matching categories (ids for mk_browse) and brand/tag pages.
Inputs: query (required), page, limit, in_stock_only.
mk_shippingDelivery date and feeARead-only
Get the nearest delivery slot and shipping fee for one product: Tehran courier and post to other cities.
Fees in Toman, 0 = free; free above free_shipping_from (null = never). same_day_seconds_left > 0: can still arrive today in Tehran.
Inputs: product_id (required).
mk_specsSpecs and comparisonARead-only
Get the spec table of 1-4 products side by side, with stock counts.
Use for specs or comparison. Each row has one value per product id (missing = none). Unknown ids: not_found.
Inputs: product_ids (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool has a distinct job, and the descriptions actively route the agent ("No keyword search here: mk_search", "Use before mk_browse", "Specs: mk_specs. Reviews: mk_reviews"). The closest pairs — mk_search vs mk_find_cheapest vs mk_deals vs mk_browse — are separated by explicit criteria (keyword vs lowest-price flat list vs discount page vs category/brand/tag listing).
Every tool uses the same mk_ prefix with snake_case and a short, predictable token. The set consistently uses noun-named getters (mk_product, mk_specs, mk_reviews, mk_shipping, mk_branches) versus action verbs for retrieval (mk_search, mk_browse, mk_find_cheapest), and that split is applied uniformly.
14 tools is well within the sweet spot and every tool maps to a real step in a shopping-research workflow (discover, narrow, inspect, compare, check reviews/shipping/branches). No obvious filler or duplicate tool that could be folded into another.
The core flow — search/browse → product → specs → reviews → shipping → physical stock — is fully covered, with categories/brands/filters supplying the ids that browse requires. The gaps are the blog branch (mk_blog_posts only lists posts 'with links' and there is no tool to fetch a post's body, so how-to/Q&A questions dead-end) and the absence of any cart/order capability, which may be intentionally out of scope.
Maintenance
Related MCP Connectors
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
MCP server of "Usilitel Signala" (usilitel-signala.ru), an online shop and installer of cellular signal boosters in Moscow and the Moscow region, Russia. It gives AI assistants live, read-only access to the catalog: repeaters, ready-made kits, boosters, antennas, coaxial cable and cable assemblies, 4G routers and accessories from VEGATEL, Baltic Signal, DalSvyaz and KROKS — more than 1,100 products. Features: • product search and comparison with live prices and stock (synced with the website every 5 minutes); • equipment picks for a site: area, mobile operator or frequency band, calls or internet; • texts of catalog sections, collections, installation services and blog articles; • recent catalog changes: new products, price and stock updates; • contacts, delivery, payment and returns; • a link to the order form on the website, pre-filled with the selection — the customer enters the phone number on the website; no personal data passes through the assistant. Read-only, no authentication required. Data language: Russian.
Merchant product catalogs for AI agents: price, availability, specs, variants, buy links. Read-only.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for the Yandex KIT e-commerce API, built with the official Model Context Protocol SDK. It exposes 61 tools over stdio to manage catalog, orders, discounts, and webhooks.973MIT
- AlicenseAqualityBmaintenanceBatch-first MCP server for product search, product detail, and anonymous shipping quotes across public storefronts and marketplaces, exposing search, product, quote, and images commands with compact JSON output for AI agents.4MIT
- AlicenseAqualityBmaintenanceTurns any JSON file (catalogue, FAQ, price list) into an MCP server with three read-only tools: list with paging, keyword search across chosen fields, and get by id. Runs over stdio for Claude Desktop, Claude Code and Cursor.3MIT
- AlicenseAqualityBmaintenanceAn unofficial, read-only MCP server that lets AI agents pull current Persian-language headlines and article text from six outlets — Mehr, Khabaronline, Hamshahri, Tabnak, Zoomit and Digiato. It exposes latest items per source and category, a time-merged overview, cross-source keyword search, and full story bodies.6113 PyPI1MIT