Skip to main content
Glama
asalbanoo-mcp

asalbanoo-mcp

by sepehr071

asalbanoo-mcp: Asal Banoo MCP server for AI agents

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

PyPI Python CI MCP Registry License: MIT mcpfarsi

Install in Cursor Install in VS Code

For AI agents · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development


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 (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, and the catalog of all Iranian MCP servers at iran-mcp (TOOLS.md, servers.json, llms.txt).

Related MCP server: shopino-mcp

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?

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

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?"

  • تخفیف‌های امروز عسل بانو روی ضد آفتاب چیه؟

  • ارزان‌ترین شامپو ضد شوره موجود در عسل بانو کدومه؟

  • نظر خریداران درباره سرم ویتامین سی چیه؟

Quick start

You need uv. No API key or account.

claude mcp add asalbanoo -- uvx asalbanoo-mcp

Settings → Developer → Edit Config, then add:

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

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

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

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

Or in ~/.codex/config.toml:

[mcp_servers.asalbanoo]
command = "uvx"
args = ["asalbanoo-mcp"]

Add to ~/.gemini/settings.json:

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

Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.

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

Tools

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

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

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

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

How it works

  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.

The shop has no public product API: prices come from listing cards, the product quick view and the site's live search, so the server parses that HTML with the Python standard library. Requests go out through a Chrome-impersonating client, at most 2 at a time with a little jitter. It solves the site's small cookie challenge (HTTP 418) automatically, retries timeouts, dropped connections, 429 and 5xx up to twice, and keeps the category and brand lists for an hour. It only reads.

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

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.

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.

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

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.

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

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.

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. Requests use a Chrome TLS and header profile. 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.

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

npx @modelcontextprotocol/inspector uvx asalbanoo-mcp

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

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

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

چه کارهایی می‌کند

  • جستجوی محصول به فارسی یا انگلیسی، مثلاً شامپو، ضد آفتاب، سرم، کرم مرطوب‌کننده یا برند (مثل vichy).

  • ارزان‌ترین محصول موجود با قیمت، تخفیف و موجودی.

  • مرور دسته‌ها و برندها با فیلتر حجم، نوع پوست و مو و بازه قیمت.

  • جزئیات محصول: قیمت هر حجم و رنگ، موجودی، ویژگی‌ها، نظرات خریداران و پاسخ فروشگاه.

  • تخفیف‌های روز به ترتیب بیشترین تخفیف.

  • مقالات و راهنماها: مراقبت از پوست و مو، مقایسه محصولات، شرایط ارسال و بازگشت کالا.

نکته‌ها

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

  • قیمت‌ها به تومان است.

  • هزینه ارسال در سایت منتشر نشده و فقط هنگام پرداخت نمایش داده می‌شود.

  • کلید API لازم نیست و روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.

نصب (اول uv را نصب کنید). در Claude Code:

claude mcp add asalbanoo -- uvx asalbanoo-mcp

در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.

نمونه پرسش‌ها

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

  • «تخفیف‌های امروز عسل بانو روی ضد آفتاب چیست؟»

  • «ضد آفتاب پوست چرب موجود در عسل بانو چند است؟»

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

Development

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

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

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

License

MIT

Available Tools

12 tools
ab_blog_postRead a blog postA
Read-onlyIdempotent

Read one blog post as plain text, plus the products and categories it links to.

Use after ab_blog_posts. Linked products: look up with ab_search; categories: ab_browse.

Inputs: post_id (required), max_chars.

ab_blog_postsBlog posts and care guidesA
Read-onlyIdempotent

List Asal Banoo blog posts (skin and hair care guides, routines, "X vs Y" comparisons), newest first.

Use for advice questions: find a post, then read it with ab_blog_post.

Inputs: page, limit, query.

ab_brandsList brandsA
Read-onlyIdempotent

List brands (about 250) with slugs and product counts, biggest first.

Use to get a brand slug. Latin queries match better ('vichy').

Inputs: limit, query.

ab_browseBrowse a category or brandA
Read-onlyIdempotent

List products of a category or brand (or the whole shop) with sort, price range, stock and attribute filters.

Use for "cheapest shampoo for oily hair". Slugs from ab_categories / ab_brands, filters from ab_filters.

Inputs: page, sort, brand, limit, +6 more.

ab_categoriesList categoriesB
Read-onlyIdempotent

List product categories (about 70) with slugs and counts.

Use to get a category slug. parent = parent category id (0 = top level); count includes out-of-stock.

Inputs: query.

ab_dealsCurrent dealsA
Read-onlyIdempotent

List discounted in-stock products, biggest discount first.

Use for "what's on sale". Ranks the first 300 deals: complete=false means more exist (see total).

Inputs: limit, category.

ab_filtersFilters of a category or brandA
Read-onlyIdempotent

List the attribute filters of a category or brand (volume, hair/skin type, gender, origin) with in-stock counts.

Use before ab_browse for a size or type.

Inputs: brand, category.

ab_find_cheapestFind cheapest productA
Read-onlyIdempotent

Find the cheapest in-stock products for a keyword, one list sorted by price (Toman).

Use for the lowest price of X. Check ab_product for the size you need. complete=false means more in-stock matches lie past scanned: raise scan.

Inputs: query (required), scan, limit, match_all_words.

ab_productProduct detailsA
Read-onlyIdempotent

Get one product: price, stock, every size/color variant with its own price and stock, facts, images.

Use after ab_search / ab_browse. Reviews: ab_reviews.

Inputs: product_id (required).

ab_reviewsProduct reviewsA
Read-onlyIdempotent

Read customers' reviews and questions about a product (newest first) with the shop's answers.

Use as a quality check or for the shop's staff advice. rating is null for a question. Dates are Jalali. count and star_counts cover all reviews on the page; truncated=true means more than limit exist.

Inputs: product_id (required), limit, full_text.

ab_shop_infoShop policies and FAQA
Read-onlyIdempotent

Read one of the shop's policy pages as plain text: FAQ as question/answer pairs, other pages as text.

Use for delivery, returns, shop address.

Inputs: topic, full_text.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools are clearly distinct, especially the list/read pairs like ab_blog_posts vs ab_blog_post and the taxonomy tools ab_categories, ab_brands, and ab_filters. Product discovery has some intentional overlap among ab_search, ab_browse, and ab_find_cheapest, but the descriptions mostly clarify keyword search vs category/brand browsing vs cheapest-price lookup.

    Naming Consistency5/5

    All tools use the same ab_ prefix followed by clear snake_case names, with a predictable verb_or_resource pattern. The naming is consistent throughout and easy to scan.

    Tool Count5/5

    Twelve tools is well within a reasonable range for a focused e-commerce catalog assistant. Each tool appears to earn its place by covering search, browsing, taxonomy, product detail, deals, reviews, blog content, and shop policies.

    Completeness4/5

    The surface covers the core read-only shopping assistant workflow: discovery, filtering, product detail, deals, reviews, blog guidance, and policy lookup. Minor gaps remain, such as keyword search/filtering for blog posts and no cart/order tools if full commerce were intended, but neither appears central to the stated tool set.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search Khanoumi's cosmetics, skin and hair care and perfume catalog, compare prices, shades, stock and reviews, and find daily deals. It also surfaces store info such as packaging, shipping and return fees, all read-only with no login or ordering.
      12
      145 PyPI
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search a catalog of roughly 960,000 fashion products across about 10,000 Iranian online and Instagram shops, comparing prices and discounts, checking per-color and per-size stock, browsing categories and curated listings, and finding similar items at other shops. It also lets agents assess shop trust signals such as ratings and buyer surveys, surface flash sales and discount codes, and read blog style guides, all read-only with no login or ordering.
      14
      138 PyPI
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search and compare home appliances, TVs, electronics and tools on the Iranian shop Baneh, find the cheapest in-stock matches, browse by category or brand, and read product details and buyer reviews. Runs read-only with no authentication, with prices returned in Toman.
      7
      137 PyPI
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search Banimode's fashion catalog in Persian and compare Toman prices, discounts, per-size stock, and customer reviews. Also surfaces today's flash deals, all through read-only tools requiring no authentication.
      7
      127 PyPI
      MIT