Metadata-Version: 2.5
Name: asalbanoo-mcp
Version: 0.5.2
Summary: Unofficial read-only MCP server for Asal Banoo: search cosmetics, skin and hair care, compare prices and variants, find deals.
Project-URL: Homepage, https://github.com/sepehr071/asalbanoo-mcp
Project-URL: Issues, https://github.com/sepehr071/asalbanoo-mcp/issues
Project-URL: Website, https://mcpfarsi.ir/servers/asalbanoo/
Author-email: Sepehr Radmard <sepehrr80@gmail.com>
License-Expression: PolyForm-Noncommercial-1.0.0
License-File: LICENSE
Keywords: ai-agents,asal-banoo,asalbanoo,cosmetics,e-commerce,haircare,iran,mcp,mcp-server,model-context-protocol,persian,price-comparison,shopping,skincare
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
Provides-Extra: browser
Requires-Dist: patchright==1.64.3; extra == 'browser'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.sepehr071/asalbanoo-mcp -->

<div align="center">

<img src="https://raw.githubusercontent.com/sepehr071/asalbanoo-mcp/main/.github/banner.png" alt="asalbanoo-mcp: unofficial Asal Banoo MCP server for Claude, Cursor and Copilot" width="100%">

# asalbanoo-mcp: Asal Banoo MCP server for AI agents

**Let your AI agent shop for cosmetics and skin care on Asal Banoo (عسل بانو).**<br>
An unofficial, read-only MCP server for [asalbanooshop.com](https://asalbanooshop.com), an Iranian online shop for skin care, hair care, make-up and perfume:<br>
search products, find the cheapest in-stock match, compare sizes and prices, read reviews and catch discounts, from Claude, Cursor or Copilot.

[![PyPI](https://img.shields.io/pypi/v/asalbanoo-mcp?color=2563eb)](https://pypi.org/project/asalbanoo-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/asalbanoo-mcp)](https://pypi.org/project/asalbanoo-mcp/)
[![CI](https://github.com/sepehr071/asalbanoo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/asalbanoo-mcp/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fasalbanoo--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=asalbanoo-mcp)
[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial-c2410c)](https://github.com/sepehr071/asalbanoo-mcp/blob/main/LICENSE)
[![mcpfarsi](https://mcpfarsi.ir/badge/asalbanoo.svg)](https://mcpfarsi.ir/servers/asalbanoo/)

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=asalbanoo&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJhc2FsYmFub28tbWNwIl19)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_asalbanoo--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=asalbanoo&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22asalbanoo-mcp%22%5D%7D)

[For AI agents](#for-ai-agents) · [Why](#why) · [What it can do](#what-it-can-do) · [Quick start](#quick-start) · [Tools](#tools) · [Good to know](#good-to-know) · [FAQ](#faq) · [Configuration](#configuration) · [فارسی](#فارسی) · [Development](#development)

</div>

---

## For AI agents

- **What:** unofficial MCP server (model context protocol) for Asal Banoo (asalbanooshop.com, عسل بانو), an Iranian skin care, hair care, make-up and perfume shop with branches in Bandar Abbas. Queries work in Persian and English.
- **Install:** `uvx asalbanoo-mcp` or `claude mcp add asalbanoo -- uvx asalbanoo-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
- **Auth:** none, no API key or account. Optional `ASALBANOO_MCP_PROXY` sets an HTTP proxy (or a comma-separated list) for requests to asalbanooshop.com; system proxy settings are ignored.
- **Access:** read-only. It cannot log in, use a cart, place orders or post reviews, so no confirmation is needed before calling any tool.
- **Tools:** 12, all prefixed `ab_`. Start with `ab_find_cheapest`, `ab_search`, `ab_product` or `ab_deals`. Typical sequence: `ab_find_cheapest` -> `ab_product` -> `ab_reviews`. Take a product's `id` from `ab_search` or `ab_browse` and pass it as `product_id` to `ab_product` and `ab_reviews`. Category and brand slugs for `ab_browse` come from `ab_categories` and `ab_brands`.
- **Units:** prices in **Toman**. `final_price` is what the buyer pays, `price` is before discount, `discount_pct` is a whole percent, ratings are 1-5 or `null`. In product lists, null fields are left out: no `price` means it equals `final_price`, no `discount_pct` means 0, no `rating` means no reviews. Review texts are cut at 400 characters (`full_text=true` on `ab_reviews` returns them whole).
- **Use when:** the user compares cosmetics and skin care prices, sizes, stock, reviews or current discounts on Asal Banoo, or wants the shop's care guides and delivery rules.
- **Do not use when:** the user wants to buy something (no cart or checkout), needs a shipping fee (the shop shows it only at checkout), or asks about another shop.
- **Machine-readable:** [`server.json`](https://github.com/sepehr071/asalbanoo-mcp/blob/main/server.json), and the catalog of all Iranian MCP servers at [iran-mcp](https://github.com/sepehr071/iran-mcp) ([TOOLS.md](https://github.com/sepehr071/iran-mcp/blob/main/TOOLS.md), [servers.json](https://github.com/sepehr071/iran-mcp/blob/main/servers.json), [llms.txt](https://github.com/sepehr071/iran-mcp/blob/main/llms.txt)).

## Why

Asal Banoo (عسل بانو) lists about 3,500 skin, hair, make-up and perfume products, and a search for
"sunscreen" mixes in eye creams, sold-out items and products that only mention sunscreen in their
description. Finding *the cheapest one you can actually order, in the size you want*, means paging
through listings and opening product pages. An agent with `asalbanoo-mcp` does that in seconds:

> **You:** Cheapest sunscreen I can order now?
>
> **Agent:** *calls* `ab_find_cheapest(query="ضد آفتاب")` → `ab_product(product_id=28470)`
>
> | Price | Product | Note |
> |---:|---|---|
> | **427,300** | ضد آفتاب دور چشم آیسول | eye area, untinted; the tinted one (432,200) is sold out |
> | **499,800** | ضدآفتاب دور چشم فتوتیپیک SPF30 درماتیپیک | eye-area, rating 1.5 |
> | **599,800** | ضد آفتاب پوست خشک درماتیپیک Hydra | face, dry skin, 5 tints up to 899,800 |
>
> The two cheapest are for the eye area. For the face, the Dermatypique Hydra is listed from 599,800 Toman,
> but only its Light Beige tint is in stock, at 899,800. Want me to check its reviews with `ab_reviews`?

<sub>Real tool output from 2026-10-06; prices change all the time. Prices are in Toman.</sub>

## What it can do

- **Search** products by name in Persian or English, with price, discount, stock and rating
- **Find the cheapest** in-stock match whose title really contains your words
- **Browse** any category or brand sorted by price, date, popularity or rating, with price range, volume and hair/skin type filters
- **Read** product details: every size/color with its own price and stock, key facts (volume, skin type, origin), reviews with the shop's answers
- **Catch deals**: everything discounted right now, biggest discount first
- **Get advice** from the shop's care guides and comparisons, plus delivery, return and wallet rules
- **Read-only by design**: no login, no cart, no orders, no reviews posted

Example prompts:

- "Cheapest anti-dandruff shampoo between 1 and 2 million Toman, and which one has the best reviews?"
- "How much is the 1000 ml Roverhair Detox shampoo, and is it in stock?"
- "Vichy Mineral 89 or Clinique Moisture Surge for oily skin?"
- "Which Asal Banoo products are discounted the most today?"
- <span dir="rtl">تخفیف&zwnj;های امروز عسل بانو روی ضد آفتاب چیه؟</span>
- <span dir="rtl">ارزان&zwnj;ترین شامپو ضد شوره موجود در عسل بانو کدومه؟</span>
- <span dir="rtl">نظر خریداران درباره سرم ویتامین سی چیه؟</span>

## Quick start

You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.

<details open>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add asalbanoo -- uvx asalbanoo-mcp
```
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings → Developer → Edit Config, then add:

```json
{
  "mcpServers": {
    "asalbanoo": { "command": "uvx", "args": ["asalbanoo-mcp"] }
  }
}
```
</details>

<details>
<summary><b>Cursor</b></summary>

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

<details>
<summary><b>VS Code (Copilot agent mode)</b></summary>

Click **Install in VS Code** above, or add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "asalbanoo": { "type": "stdio", "command": "uvx", "args": ["asalbanoo-mcp"] }
  }
}
```
</details>

<details>
<summary><b>Codex CLI</b></summary>

```bash
codex mcp add asalbanoo -- uvx asalbanoo-mcp
```

Or in `~/.codex/config.toml`:

```toml
[mcp_servers.asalbanoo]
command = "uvx"
args = ["asalbanoo-mcp"]
```
</details>

<details>
<summary><b>Gemini CLI</b></summary>

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "asalbanoo": { "command": "uvx", "args": ["asalbanoo-mcp"] }
  }
}
```
</details>

<details>
<summary><b>Windsurf</b></summary>

Add the Claude Desktop block to `~/.codeium/windsurf/mcp_config.json`.
</details>

<details>
<summary><b>Anything else</b></summary>

It's a standard stdio MCP server: run `uvx asalbanoo-mcp`, or `pip install asalbanoo-mcp` and run `asalbanoo-mcp`.
</details>

## Tools

All 12 tools are prefixed `ab_` and annotated `readOnlyHint: true`. They return compact JSON, so they don't flood the agent's context.

<details open>
<summary><b>Find products</b> (7)</summary>

| Tool | What it does |
|---|---|
| `ab_search` | Search by keyword: price, discount, stock, rating, with sort and price range |
| `ab_find_cheapest` | Cheapest in-stock matches for a keyword, one flat list (titles must contain every word) |
| `ab_browse` | A category, brand or the whole shop sorted by price / date / popularity / rating, with price range and filters |
| `ab_filters` | Volume, hair/skin type, gender and origin filters of a category or brand, with counts |
| `ab_categories` | Product categories (about 70) with slugs and product counts |
| `ab_brands` | Brands (about 250) with slugs and product counts |
| `ab_deals` | Everything discounted and in stock, biggest discount first |
</details>

<details open>
<summary><b>One product</b> (2)</summary>

| Tool | What it does |
|---|---|
| `ab_product` | Price, discount, stock (exact count when low), every size/color variant, brand, rating, key facts |
| `ab_reviews` | Customer reviews and questions with star breakdown and the shop's answers |
</details>

<details open>
<summary><b>Shop info and blog</b> (3)</summary>

| Tool | What it does |
|---|---|
| `ab_shop_info` | FAQ, terms, about and contact pages as text: delivery (outside Bandar Abbas Post Pishtaz 7-10 working days; Bandar Abbas courier, next day before 13:00), returns, wallet, branches |
| `ab_blog_posts` | Skin and hair care guides and comparisons, newest first |
| `ab_blog_post` | One guide as plain text, with the products and categories it links to |
</details>

## 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 doesn't use it for prices.
- **Images**: every product has `image` (absolute, percent-encoded https URL); `ab_product` also has `images` (gallery). To download one yourself send a browser `User-Agent`: plain python/httpx gets HTTP 403 from the site's WAF.
- **Sizes and colors**: a product with variants is listed at its cheapest variant (`final_price`) up to `max_price`, with the biggest variant discount as `discount_pct`; `ab_product` gives each variant's price, stock and `max_qty`.
- **Delivery**: outside Bandar Abbas only by Post Pishtaz, 7-10 working days. In Bandar Abbas by courier, next day when ordered before 13:00, or pick up in the two branches. The shipping fee is shown only at checkout and is not published.
- **Stock**: `in_stock` means orderable online now; `stock_status` shows the exact count when few are left ("فقط 2 عدد در انبار موجود است"). When nothing in stock matches, `ab_search` adds `out_of_stock_matches` so a sold-out brand isn't mistaken for one the shop never carried.
- **Ratings are 1-5**, `null` when nobody has reviewed the product yet. Review dates are Jalali (for example `1405-07-13`).
- **Persian queries match best** (`شامپو`, `ضد آفتاب`), but English brand names work too (`vichy`, `la roche`). There is no separate autocomplete tool: `ab_search` covers the site's header live search.
- **Search also matches descriptions**, so check titles; `ab_find_cheapest` filters on titles for you.
- **Privacy**: review authors' contact details are never extracted or returned.
- **Rate limits**: none seen at about one request per second. The site's `robots.txt` disallows the listing query parameters for crawlers, so please keep request rates low.
- **What it does not do**: no login, cart, checkout, coupons, wallet, wishlist, posted reviews or contact forms; no shipping fee (not published); no other shops.

## FAQ

<details>
<summary><b>Is there an Asal Banoo API or MCP server for AI agents?</b></summary>

Asal Banoo doesn't publish an official API for agents. `asalbanoo-mcp` is an unofficial MCP server that reads the
public pages and endpoints of asalbanooshop.com and exposes them as 12 read-only tools.
</details>

<details>
<summary><b>Can it place an order for me?</b></summary>

No, and that's deliberate. It has no login and never touches the cart, checkout, wallet, wishlist or review endpoints.
The agent finds the best option; you buy it on asalbanooshop.com.
</details>

<details>
<summary><b>Why does <code>ab_find_cheapest</code> skip some items?</b></summary>

The site's search also matches product descriptions, so `ab_find_cheapest` keeps only in-stock items whose title
contains every word of your query (`match_all_words: false` turns that off). It scans the 150 cheapest in-stock
results by default; `complete: false` in the reply means more lie past that, so raise `scan` (up to 300).
</details>

<details>
<summary><b>How do I use Asal Banoo with Claude, Cursor or Copilot?</b></summary>

Install the server once (see [Quick start](#quick-start)), then ask in plain language, in Persian or English. In Claude Code
the install is `claude mcp add asalbanoo -- uvx asalbanoo-mcp`.
</details>

<details>
<summary><b>Are prices in Rial or Toman?</b></summary>

Toman. The site's structured data uses Rial, but the server reads the Toman prices shown on the pages.
</details>

<details>
<summary><b>Is it official, safe and free?</b></summary>

It is unofficial and free for non-commercial use. It is read-only, needs no account or API key, and runs on your machine with no
hosted server in between.
</details>

<details>
<summary><b>I get "Could not reach asalbanooshop.com" or a bot challenge error</b></summary>

The site answers new visitors with a small cookie challenge (HTTP 418); the server solves it automatically and
retries timeouts, dropped connections, 429 and 5xx up to twice. If the
site serves a browser check instead, install `asalbanoo-mcp[browser]` and run `patchright install chromium`; the server
then clears it in a headless browser. If it still fails, check your internet connection. System proxy variables are
ignored on purpose; set `ASALBANOO_MCP_PROXY` if you need a proxy.
</details>

<details>
<summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary>

Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`.
</details>

<details>
<summary><b>How do I debug what the agent sees?</b></summary>

```bash
npx @modelcontextprotocol/inspector uvx asalbanoo-mcp
```
</details>

## Configuration

| Variable | Default | Meaning |
|---|---|---|
| `ASALBANOO_MCP_PROXY` | unset | Optional HTTP proxy URL for asalbanooshop.com requests, e.g. `http://user:pass@host:port`; system proxy settings are ignored. A comma-separated list is used one at a time, moving on after a block or connect error |

<a id="فارسی"></a>

## فارسی: سرور MCP عسل بانو

<div dir="rtl">

**asalbanoo-mcp** یک سرور MCP غیررسمی برای فروشگاه اینترنتی **عسل بانو** (asalbanooshop.com) است؛ فروشگاه ایرانی محصولات مراقبت از پوست، مراقبت از مو، آرایشی و عطر. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می&zwnj;دهد در عسل بانو جستجو کند،
ارزان&zwnj;ترین محصول موجود را پیدا کند، قیمت حجم&zwnj;ها و رنگ&zwnj;های مختلف را مقایسه کند، نظرات و پاسخ مشاوران را بخواند و تخفیف&zwnj;های روز را ببیند.

**چه کارهایی می&zwnj;کند**

- **جستجوی محصول** به فارسی یا انگلیسی، مثلاً شامپو، ضد آفتاب، سرم، کرم مرطوب&zwnj;کننده یا برند (مثل vichy).
- **ارزان&zwnj;ترین محصول موجود** با قیمت، تخفیف و موجودی.
- **مرور دسته&zwnj;ها و برندها** با فیلتر حجم، نوع پوست و مو و بازه قیمت.
- **جزئیات محصول**: قیمت هر حجم و رنگ، موجودی، ویژگی&zwnj;ها، نظرات خریداران و پاسخ فروشگاه.
- **تخفیف&zwnj;های روز** به ترتیب بیشترین تخفیف.
- **مقالات و راهنماها**: مراقبت از پوست و مو، مقایسه محصولات، شرایط ارسال و بازگشت کالا.

**نکته&zwnj;ها**

- فقط خواندنی است: وارد حساب نمی&zwnj;شود، سبد خرید نمی&zwnj;سازد، سفارش ثبت نمی&zwnj;کند و نظر نمی&zwnj;فرستد. خرید را خودتان در سایت انجام می&zwnj;دهید.
- قیمت&zwnj;ها به تومان است.
- هزینه ارسال در سایت منتشر نشده و فقط هنگام پرداخت نمایش داده می&zwnj;شود.
- کلید API لازم نیست و روی سیستم خود شما اجرا می&zwnj;شود و به هیچ سرور واسطی داده نمی&zwnj;فرستد.

**نصب** (اول [uv](https://docs.astral.sh/uv/getting-started/installation/) را نصب کنید). در Claude Code:

</div>

```bash
claude mcp add asalbanoo -- uvx asalbanoo-mcp
```

<div dir="rtl">

در Claude Desktop، Cursor و بقیه برنامه&zwnj;ها همان تنظیم بخش [Quick start](#quick-start) را بگذارید.

**نمونه پرسش&zwnj;ها**

- «ارزان&zwnj;ترین شامپو ضد شوره بین ۱ تا ۲ میلیون تومان کدام است و نظر خریداران درباره&zwnj;اش چیست؟»
- «تخفیف&zwnj;های امروز عسل بانو روی ضد آفتاب چیست؟»
- «ضد آفتاب پوست چرب موجود در عسل بانو چند است؟»

برای جستجو کافی است محصول یا برند را به فارسی یا انگلیسی بنویسید، مثلاً «ضد آفتاب» یا «vichy».

</div>

## Development

```bash
git clone https://github.com/sepehr071/asalbanoo-mcp && cd asalbanoo-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q          # offline, against recorded responses
uv run python -m pytest -m live -q  # real asalbanooshop.com
uv build
```

Tools live in `src/asalbanoo_mcp/catalog.py`, `product.py` and `content.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](https://registry.modelcontextprotocol.io), and creates the GitHub Release.

## Related servers

- [iran-mcp](https://github.com/sepehr071/iran-mcp): catalog of all Iranian-service MCP servers
- [Khanoumi MCP server](https://github.com/sepehr071/khanoumi-mcp) for cosmetics and skin care prices and shades
- [Shopino MCP server](https://github.com/sepehr071/shopino-mcp) for fashion across thousands of Iranian shops
- [Banimode MCP server](https://github.com/sepehr071/banimode-mcp) for fashion prices and sizes on Banimode
- [Digikala MCP server](https://github.com/sepehr071/digikala-mcp) for products and prices on Digikala
- [Torob MCP server](https://github.com/sepehr071/torob-mcp) for comparing prices across Iranian shops
- Listed on [mcpfarsi.ir](https://mcpfarsi.ir/servers/asalbanoo/), the Persian MCP marketplace

If this saves you clicks, a star helps others find it.

## Disclaimer

Unofficial and not affiliated with or endorsed by Asal Banoo. It is read-only and uses the public pages and
endpoints of the asalbanooshop.com website, which can change without notice. Please keep request rates reasonable.

## Author

<a href="https://www.linkedin.com/in/sepehr-radmard"><img src="https://raw.githubusercontent.com/sepehr071/iran-mcp/main/assets/author-banner.png" alt="Sepehr Radmard: open-source MCP servers for the Iranian web. LinkedIn: linkedin.com/in/sepehr-radmard" width="100%"></a>

Built and maintained by **Sepehr Radmard** (سپهر رادمرد). Connect on [LinkedIn](https://www.linkedin.com/in/sepehr-radmard) or follow [@sepehr071 on GitHub](https://github.com/sepehr071) for more MCP servers for Iranian websites, all listed in [iran-mcp](https://github.com/sepehr071/iran-mcp). If this saves you time, a star on the repo helps other people find it.

## مجوز استفاده (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/asalbanoo-mcp/blob/main/LICENSE). نسخه&zwnj;های پیش از 0.5.1 با مجوز MIT منتشر شده&zwnj;اند و همان مجوز را دارند.

Free for personal and non-commercial use under the [PolyForm Noncommercial License 1.0.0](https://github.com/sepehr071/asalbanoo-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.5.1 were released under MIT and stay under it.
