asalbanoo-mcp

<!-- 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 🧴

**Unofficial, read-only MCP server that lets your AI agent shop for cosmetics and skin care on Asal Banoo (عسل بانو), an Iranian online shop.**<br>
Search shampoos, sunscreens, serums and make-up, compare real prices and sizes,<br>
read reviews and the shop's skin advice, check stock and catch today's discounts, all 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: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/asalbanoo-mcp/blob/main/LICENSE)

[![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)

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

</div>

---

## For AI agents

- **What:** unofficial MCP server for Asal Banoo (asalbanooshop.com, عسل بانو), an Iranian skin care, hair care, make-up and perfume shop. Queries work in Persian and English; prices are in Toman.
- **Install:** `claude mcp add asalbanoo -- uvx asalbanoo-mcp` (stdio transport, needs [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+).
- **Auth:** none. Optional `ASALBANOO_MCP_PROXY` sets an HTTP proxy for requests to asalbanooshop.com.
- **Access:** read-only. No login, cart, orders or posted reviews, so no write tools exist.
- **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`.
- **Use when:** comparing cosmetics and skin care prices, sizes, stock, reviews or current discounts on Asal Banoo.
- **Do not use when:** the user wants to buy something (no cart or checkout), or needs a shipping fee (the shop shows it only at checkout).
- **Output:** compact JSON. `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). Pass a product's `id` from `ab_search` or `ab_browse` as `product_id` to `ab_product` and `ab_reviews`.
- **Machine-readable:** [`server.json`](server.json), and the catalog of all Iranian MCP servers at [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp) ([TOOLS.md](https://github.com/sepehr071/awesome-iran-mcp/blob/main/TOOLS.md), [servers.json](https://github.com/sepehr071/awesome-iran-mcp/blob/main/servers.json), [llms.txt](https://github.com/sepehr071/awesome-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

## 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`.
</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>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>

Then just ask:

- "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?"
- <span dir="rtl">تخفیف&zwnj;های امروز عسل بانو روی ضد آفتاب چیه؟</span>

## How it works

```text
  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  asalbanoo-mcp  (runs on your machine)
      │
      │  HTTPS
      └──────▶  asalbanooshop.com   listing pages, quick-view fragments, WordPress REST
```

`asalbanoo-mcp` runs locally and calls the same public pages and endpoints the asalbanooshop.com website uses.
There's no hosted server in between, no API key, and nothing about you is sent anywhere else.

## Tools

<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 with slugs and product counts |
| `ab_brands` | Brands 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>

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

## 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, sto