Metadata-Version: 2.5
Name: emalls-ir-mcp
Version: 0.1.1
Summary: Unofficial read-only MCP server for Emalls (emalls.ir), the Iranian price comparison site: products, shop offers, price history.
Project-URL: Homepage, https://github.com/sepehr071/emalls-ir-mcp
Project-URL: Issues, https://github.com/sepehr071/emalls-ir-mcp/issues
Project-URL: Website, https://mcpfarsi.ir/
Author-email: Sepehr Radmard <sepehrr80@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,ecommerce,emalls,emalls-ir,iran,mcp,model-context-protocol,persian,price-comparison,price-history,shopping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: curl-cffi>=0.16.3
Requires-Dist: httpx-curl-cffi>=0.1.5
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.2
Description-Content-Type: text/markdown

<!-- 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: MIT](https://img.shields.io/badge/license-MIT-16a34a)](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) · MIT License
