MasterKala

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-mcp or claude 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 with mk_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_price is what you pay), ratings 1-5 (null = no reviews). Numeric product ids pass between tools.
• Machine-readable: server.json and the 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 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 Code

claude mcp add masterkala -- uvx masterkala-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

{

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

</details>

Cursor

Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

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"] } } }

</details>

Codex CLI

codex mcp add masterkala -- uvx masterkala-mcp

Or in ~/.codex/config.toml:

[mcp_servers.masterkala]

command = "uvx" args = ["masterkala-mcp"]

</details>

Gemini CLI

Add to ~/.gemini/settings.json:

{

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

</details>

Windsurf

Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.

Anything else

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.

Find products (7)

One product (5)

Blog (2)

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 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.

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).
• Images: every product has 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, `st