asalbanoo-mcp: unofficial Asal Banoo MCP server for Claude, Cursor and Copilot

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.
Search shampoos, sunscreens, serums and make-up, compare real prices and sizes,
read reviews and the shop's skin advice, check stock and catch today's discounts, all from Claude, Cursor or Copilot.

Quick start · For AI agents · What it can do · Tools · FAQ · فارسی

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 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. Pass a product's id from ab_search or ab_browse as product_id to ab_product and ab_reviews.
Machine-readable: server.json, and the catalog of all Iranian MCP servers at awesome-iran-mcp (TOOLS.md, servers.json, ).

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?

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

_{Real tool output from 2026-10-06; prices change all the time. Prices are in Toman.}

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. No API key or account.

Claude Code

Terminal

claude mcp add asalbanoo -- uvx asalbanoo-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

config.json

{
  "mcpServers": {
    "asalbanoo": { "command": "uvx", "args": ["asalbanoo-mcp"] }
  }
}

Cursor

Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json.

VS Code (Copilot agent mode)

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

config.json

{
  "servers": {
    "asalbanoo": { "type": "stdio", "command": "uvx", "args": ["asalbanoo-mcp"] }
  }
}

Anything else

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

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?"
تخفیف‌های امروز عسل بانو روی ضد آفتاب چیه؟

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

🔎 Find products (7)

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

📋 One product (2)

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

📚 Shop info and blog (3)

Tool	What it does
`ab_shop_info`	FAQ, terms, about and contact pages as text: delivery times, 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

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, 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.
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.

FAQ

Can it place an order for me?

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.

Why does ab_find_cheapest skip some items?

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).

Is there an Asal Banoo API or MCP server for AI agents?

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.

How do I use Asal Banoo with Claude, Cursor or Copilot?

Install the server once (see Quick start), then ask in plain language, in Persian or English. In Claude Code the install is claude mcp add asalbanoo -- uvx asalbanoo-mcp.

Is it official, safe and free?

It is unofficial and free (MIT). It is read-only, needs no account or API key, and runs on your machine with no hosted server in between.

I get "Could not reach asalbanooshop.com" or a bot challenge error

The site answers new visitors with a small cookie challenge (HTTP 418); the server solves it automatically and retries a dropped connection once. If it still fails, check your internet connection. System proxy variables are ignored on purpose; set ASALBANOO_MCP_PROXY if you need a proxy.

Claude Desktop says uvx is not found

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

How do I debug what the agent sees?

Terminal

npx @modelcontextprotocol/inspector uvx asalbanoo-mcp

Configuration

Variable	Default	Meaning
`ASALBANOO_MCP_PROXY`	unset	HTTP proxy for every request, e.g. `http://user:pass@host:port`

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

asalbanoo-mcp یک سرور MCP غیررسمی برای فروشگاه ایرانی عسل بانو است و به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در فروشگاه عسل بانو جستجو کند، ارزان‌ترین محصول موجود را پیدا کند، قیمت حجم‌ها و رنگ‌های مختلف را مقایسه کند، نظرات و پاسخ مشاوران را بخواند و تخفیف‌های روز را ببیند.

فقط خواندنی است: وارد حساب نمی‌شود، سبد خرید نمی‌سازد، سفارش ثبت نمی‌کند و نظر نمی‌فرستد.
قیمت‌ها به تومان است.
روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.

نصب در Claude Code:

Terminal

claude mcp add asalbanoo -- uvx asalbanoo-mcp

بعد بپرسید: «ارزان‌ترین شامپو ضد شوره بین ۱ تا ۲ میلیون تومان کدام است و نظر خریداران درباره‌اش چیست؟»

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

Development

bash

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

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, and creates the GitHub Release.

Related servers

Khanoumi MCP server for cosmetics and skin care prices and shades
Shopino MCP server for fashion across thousands of Iranian shops
All Iranian MCP servers: awesome-iran-mcp

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

Disclaimer

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

License

MIT