Skip to main content
Glama
README.md
<!-- mcp-name: io.github.sepehr071/emalls-ir-mcp -->

# emalls-ir-mcp: Emalls (ایمالز) price comparison MCP server for AI agents

**emalls-ir-mcp is an unofficial, read-only MCP server that gives AI agents the Emalls (emalls.ir) price comparison data of Iranian shops.**<br>
Its 10 tools search products with price and category filters, list the shops selling a product with their prices,<br>
show specs and price history, and look up shop profiles. No API key or Emalls account is needed.

[![PyPI](https://img.shields.io/pypi/v/emalls-ir-mcp?color=2563eb)](https://pypi.org/project/emalls-ir-mcp/)
[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial-c2410c)](https://github.com/sepehr071/emalls-ir-mcp/blob/main/LICENSE)

[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)

---

## For AI agents

- **What:** unofficial MCP server (model context protocol) for emalls.ir, an Iranian price comparison site: product search with price, category and sort filters, per-product shop offers (price, city, rating, warranty), specs, price history and shop profiles.
- **Install:** `uvx emalls-ir-mcp` or `claude mcp add emalls -- uvx emalls-ir-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
- **Auth:** none. Optional `EMALLS_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
- **Access:** read-only. It cannot log in, buy, rate or report, so no confirmation is needed before calling any tool.
- **Tools:** 10, all prefixed `em_`. Typical sequences: `em_search` -> `em_offers`; `em_categories` -> `em_search(category_id=...)`; `em_offers` -> `em_shop`; `em_search` -> `em_price_history`; `em_filters` -> `em_search(brand_id=..., attributes=[...])`; `em_search` -> `em_similar` -> `em_compare`.
- **Use when:** the user asks what a product costs in Iran, which shop is cheapest or in a given city, whether a price is rising or falling, what a model's specs are, or whether a shop is established.
- **Do not use when:** the user wants to buy (it returns Emalls click-through links but never follows them) or needs prices outside Iran.
- **Output:** compact JSON. Prices are Toman (1 Toman = 10 Rial). Product and shop text is Persian as the site has it.
- **Machine-readable:** [`server.json`](https://github.com/sepehr071/emalls-ir-mcp/blob/main/server.json).

## Quick start

```bash
claude mcp add emalls -- uvx emalls-ir-mcp
```

Or in any MCP client config: `{"command": "uvx", "args": ["emalls-ir-mcp"]}`.
From outside Iran, the Emalls site answered through a Turkish proxy too; set `EMALLS_MCP_PROXY=http://host:port` if your line is blocked.

## Tools

| Tool | What it does |
|---|---|
| `em_search` | Products by words, category, brand, spec options, min/max price (Toman), sort (popular, cheapest, expensive, newest), in-stock, paging |
| `em_filters` | Brand ids and spec filter options (RAM, storage, ...) of a category, for `em_search` |
| `em_categories` | Category ids by words (with popular search phrases), or the category tree |
| `em_product` | Title, category path, brand, lowest and highest price, rating, specs |
| `em_compare` | 2-5 products side by side: prices, rating, only the specs that differ |
| `em_similar` | Products the site lists as similar, with lowest price and shop count |
| `em_offers` | Shops selling a product, cheapest first; filter by city, established shops, in-person; sort by rating |
| `em_price_history` | Average price over about 3 months, optionally one shop's own series |
| `em_shop` | A shop's public profile: rating, website, address, phone, time with Emalls, trust badge; optional recent customer reviews |
| `em_shops` | Shop name to id |

## FAQ

**Are the prices live?** They are what Emalls shows when the call is made (cached up to 2 minutes). Shops update through the day; the final price is the shop's own at checkout.

**Why do some `em_search` rows have no `id`?** Those are single-shop listings without a product page; they carry the shop and a `buy_url`.

**Is this affiliated with Emalls?** No. It reads the public pages and the site's own page scripts' endpoints, gently (small caches, a few parallel requests).

## فارسی

emalls-ir-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای ایمالز (emalls.ir) است: جستجوی کالا با فیلتر قیمت و دسته، فهرست فروشگاه‌ها با ارزان‌ترین قیمت، مشخصات فنی، نمودار قیمت و اطلاعات فروشگاه. قیمت‌ها به تومان هستند. نصب: `uvx emalls-ir-mcp`.

---

Built by [Sepehr Radmard](https://github.com/sepehr071) · [LinkedIn](https://linkedin.com/in/sepehr-radmard)

## مجوز استفاده (License)

<a href="https://www.linkedin.com/in/sepehr-radmard"><img src="https://raw.githubusercontent.com/sepehr071/iran-mcp/main/assets/license-banner.png" alt="استفادهٔ شخصی و غیرتجاری رایگان است؛ برای استفادهٔ تجاری با سپهر رادمرد تماس بگیرید. Free for personal and non-commercial use; commercial use needs a license." width="100%"></a>

**استفادهٔ شخصی و غیرتجاری رایگان است.** استفاده در شرکت، محصول پولی یا پروژهٔ مشتری به مجوز تجاری نیاز دارد؛ از راه [لینکدین](https://www.linkedin.com/in/sepehr-radmard) یا [گیت&zwnj;هاب](https://github.com/sepehr071) با سپهر رادمرد تماس بگیرید. متن کامل: [PolyForm Noncommercial 1.0.0](https://github.com/sepehr071/emalls-mcp/blob/main/LICENSE). نسخه&zwnj;های پیش از 0.2.1 با مجوز MIT منتشر شده&zwnj;اند و همان مجوز را دارند.

Free for personal and non-commercial use under the [PolyForm Noncommercial License 1.0.0](https://github.com/sepehr071/emalls-mcp/blob/main/LICENSE). Using it in a company, a paid product or a client project needs a commercial license: contact Sepehr Radmard on [LinkedIn](https://www.linkedin.com/in/sepehr-radmard) or [GitHub](https://github.com/sepehr071). Versions before 0.2.1 were released under MIT and stay under it.

TDQS

A4.4/5.0

Scored across 10 tools

Disambiguation5/5

Each tool maps to a distinct step in product research: search/discovery, product detail, offers, price history, comparison, similar alternatives, category/filter lookup, and shop lookup/profile. The only close pair, em_shop and em_shops, is clearly separated as profile-by-id versus name search. Descriptions explicitly sequence usage, reducing misselection.

Naming Consistency5/5

All tools use the same em_ prefix and snake_case, with concise resource/action-oriented names such as em_search, em_offers, and em_price_history. There is a minor noun/verb mix, but the convention is consistent and predictable throughout.

Tool Count5/5

Ten tools is well within the ideal 3-15 range and each tool covers a distinct capability for an Iranian price-comparison domain. There is no obvious redundancy or filler in the set.

Completeness5/5

The surface covers the full read-only workflow: discovery via search, categories, and filters; product details, similar products, and comparison; offers and price history; and shop search/profile. Purchase/checkout is intentionally handled by click-through buy_url, so no major domain gap is apparent.

Maintenance

ActivityNo data
ResponsivenessOutdated data