What MasterKala MCP server does
MasterKala MCP server exposes MasterKala, an Iranian gadget and mobile-accessories shop, through a read-only MCP interface. It is suited to product discovery and purchase research rather than completing a transaction. Agents can search in Persian or English and receive structured product information with prices in Toman; final_price represents the current payable price.
The MasterKala MCP server covers common research tasks such as locating an in-stock power bank, comparing earbuds, checking a product's reviews, finding current discounts, and estimating delivery. It can also return MasterKala shop locations and content from the store's buying guides and comparison blog.
How it works
The server runs on the user's machine and communicates with an AI client over MCP using stdio. It then makes HTTPS requests to the public endpoints and page data used by masterkala.com. There is no hosted intermediary described in the project, and the server does not require a MasterKala account or API key.
Responses are compact, structured JSON. Product IDs can be passed from one tool to another, making workflows such as mk_find_cheapest, followed by mk_product and mk_shipping, possible. Queries can be written in Persian or English.
Setup and configuration
Install uv with Python 3.10 or newer, then run the package with:
The same package can be installed with pip and started using the masterkala-mcp command. Claude Code can register it with claude mcp add masterkala -- uvx masterkala-mcp. Claude Desktop, Cursor, and VS Code can use a stdio configuration whose command is uvx and whose argument is masterkala-mcp.
No API key or account is needed. MASTERKALA_MCP_PROXY is an optional setting for an HTTP proxy, or a comma-separated list of proxies, used for requests to masterkala.com.
Tools and capabilities
The 14 tools use the mk_ prefix:
- Search keywords, identify matching categories and tags, and find the cheapest in-stock matches while excluding accessories.
- Browse categories, brands, or tags with sorting, price ranges, and filters; list category IDs, brand slugs, and available filter IDs.
- Retrieve discounts ordered by discount size and including remaining time.
- Inspect product price, discount, stock status and count, colors, brand, category, rating, and shops carrying the item.
- Compare specifications for one to four products side by side.
- Read customer reviews, star distributions, and store replies.
- Check the next delivery slot, shipping fee, and same-day cutoff for Tehran and other cities by post.
- Find physical branch addresses, telephone numbers, and map locations.
- Read buying guides, comparisons, how-to posts, and questions with store responses.
Limitations and notes
The MasterKala MCP server is read-only. It cannot log in, add products to a cart, place orders, or publish reviews, so it should not be used as a checkout mechanism. Delivery information is an estimate for Tehran and for other cities by post, based on a default Tehran address.
Prices, discounts, stock, delivery slots, and deal timers can change. Product ratings use a one-to-five scale, with null indicating that no reviews are available. The service is intended for information retrieval from MasterKala rather than broader marketplace comparisons.