masterkala-mcp
Advanced tools
Unofficial read-only MCP server for MasterKala: search gadgets and accessories, compare prices and specs, find deals.
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
uvx masterkala-mcp or claude mcp add masterkala -- uvx masterkala-mcp. Transport: stdio. Needs uv (Python 3.10+).MASTERKALA_MCP_PROXY (HTTP proxy URL, or a comma-separated list, for requests to masterkala.com); system proxy settings are ignored.mk_. Start with mk_find_cheapest, mk_search, mk_deals, mk_browse.
Typical sequence: mk_find_cheapest -> mk_product -> mk_shipping.final_price is what you pay), ratings 1-5 (null = no reviews). Numeric product ids pass between tools.server.json and the
iran-mcp catalog (TOOLS.md, servers.json, llms.txt).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.
Example prompts:
You need uv. No API key or account.
claude mcp add masterkala -- uvx masterkala-mcp
Settings → 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-mcp
Or 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.
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 |
|---|---|
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 sorted by payable price (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 (about 100 main categories) |
mk_brands | Brands and their slugs (about 135) |
mk_deals | Everything on the discount page, biggest discount first, with the time left |
| 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 in Tehran with address, phone and map location |
| 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 JSON, so they don't flood the agent's context.
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.
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.
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.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".in_stock means orderable online now. Other statuses: ناموجود (sold out), به زودی (coming soon), موجود در شعب حضوری (only in the physical shops).image, an absolute https URL (328 px webp from mk_search, mk_find_cheapest and mk_browse; 240 px from mk_deals; the original jpg from mk_specs). mk_product gives a 600 px image plus an images list (up to 4). Null/empty fields are omitted from results, stock_status only appears when it is not "موجود" (in stock), and review / comment text is cut to 400 characters (blog threads keep 3 replies, more_replies counts the rest).null when nobody has reviewed the product yet.هندزفری, پاوربانک), but English brand and model names work too (xiaomi, Buds Pro).mk_search or mk_find_cheapest; use mk_browse with a category id, brand slug or tag id when you need sorting, a price range or filters.MASTERKALA_MCP_PROXY if you need one (see Configuration).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.
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.
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.
uvx is not foundUse the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
npx @modelcontextprotocol/inspector uvx masterkala-mcp
| Variable | Default | Meaning |
|---|---|---|
MASTERKALA_MCP_PROXY | unset | Optional HTTP proxy URL for every request to masterkala.com, e.g. http://user:pass@host:port; system proxy settings are ignored. A comma-separated list is used one at a time: the next proxy takes over when one is blocked or cannot connect |
masterkala-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای مسترکالا، فروشگاه اینترنتی گجت و لوازم جانبی موبایل در ایران، است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در مسترکالا جستجو کند، ارزان‌ترین کالای موجود را پیدا کند، مشخصات و نظرات را مقایسه کند و زمان و هزینه ارسال و تخفیف‌های روز را ببیند.
چه کارهایی می‌کند
نکته‌ها
MASTERKALA_MCP_PROXY را روی یک پراکسی HTTP بگذارید.نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add masterkala -- uvx masterkala-mcp
در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسش‌ها
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.
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.
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.
If this saves you clicks, a star helps others find it.
FAQs
Unofficial read-only MCP server for MasterKala: search gadgets and accessories, compare prices and specs, find deals.
The pypi package masterkala-mcp receives a total of 578 weekly downloads. As such, masterkala-mcp popularity was classified as not popular.
We found that masterkala-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.