banimode-mcp
<!-- mcp-name: io.github.sepehr071/banimode-mcp -->
# banimode-mcp: Banimode MCP server for AI agents
**Let your AI agent shop for fashion on [Banimode](https://www.banimode.com) (بانی‌مد).**<br>
An unofficial, read-only MCP server for Banimode, an Iranian online fashion and lifestyle store: search clothing, shoes, bags and accessories,
compare prices in Toman, check which sizes are in stock, read customer reviews and catch today's flash sales, all from Claude, Cursor or Copilot.
[](https://pypi.org/project/banimode-mcp/)
[](https://pypi.org/project/banimode-mcp/)
[](https://github.com/sepehr071/banimode-mcp/actions/workflows/ci.yml)
[](https://registry.modelcontextprotocol.io/?q=banimode-mcp)
[](https://github.com/sepehr071/banimode-mcp/blob/main/LICENSE)
[](https://mcpfarsi.ir/servers/banimode/)
[](https://cursor.com/en/install-mcp?name=banimode&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJiYW5pbW9kZS1tY3AiXX0=)
[](https://vscode.dev/redirect/mcp/install?name=banimode&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22banimode-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) · [FAQ](#faq) · [فارسی](#فارسی)
---
## For AI agents
- **What:** unofficial MCP server for Banimode (banimode.com, بانی‌مد), an Iranian fashion shop (clothing, shoes, bags, watches, beauty, home). Queries work best in Persian; prices are in Toman.
- **Install:** `uvx banimode-mcp` or `claude mcp add banimode -- uvx banimode-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
- **Auth:** none, no API key or account. Optional `BANIMODE_MCP_PROXY` (HTTP proxy, or a comma-separated list tried in turn).
- **Access:** read-only. No login, cart, orders or posted reviews, so no confirmation is needed before calling any tool.
- **Tools:** 7, all prefixed `bm_`. Start with `bm_search`, `bm_browse` or `bm_deals`. Typical sequence: `bm_search` -> `bm_product` -> `bm_reviews`.
- **Use when:** comparing fashion prices, sizes in stock, discounts or reviews on Banimode.
- **Do not use when:** the user wants to buy (no cart or checkout) or needs the shipping fee (shown only at checkout).
- **Output:** compact JSON. Prices in Toman: `final_price` is what the buyer pays, `price` is the list price before discount (left out when equal), `discount_pct` is a whole percent. A search card is one product in one color, so an id can repeat with other colors; `bm_product` lists every color with stock per size.
- **Machine-readable:** [`server.json`](https://github.com/sepehr071/banimode-mcp/blob/main/server.json) and the
[iran-mcp catalog](https://github.com/sepehr071/iran-mcp) (`TOOLS.md`, `servers.json`, `llms.txt`).
## Why
Fashion shopping means many tabs: the same dress in five colors, sizes that are sold out, a discount that may or may not be real,
and reviews buried at the bottom of the page. With `banimode-mcp` an agent filters by price and size, hides sold-out items,
sorts by discount and reads the reviews for you, then gives you a short list with links.
## What it can do
- **Search** by keyword with sort (cheapest, most expensive, biggest discount, newest), a Toman price range, size, in-stock, category and brand filters
- **Browse** a category and/or a brand, using ids from `bm_categories` and `bm_brands`
- **Check a product**: every color with price, discount, stock per size, features and a short description
- **Read reviews**: stars, text, date and the shop's answer
- **Catch flash sales**: today's time-limited discounts with the time left
- **Read-only by design**: no login, no cart, no orders
Example prompts:
- "Find women's black sneakers on Banimode under 2 million Toman, size 38 in stock, biggest discount first."
- "What are today's flash sales on Banimode? Show only the ones with more than 40% off."
- "Show me the reviews of this product and tell me if the sizing runs small."
- <span dir="rtl">مانتو مجلسی زنانه زیر ۳ میلیون تومان در بانی‌مد پیدا کن.</span>
- <span dir="rtl">ارزان‌ترین کفش اسپرت مردانه سایز ۴۳ که موجود باشد کدام است؟</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 banimode -- uvx banimode-mcp
```
</details>
<details>
<summary><b>Claude Desktop</b></summary>
Settings -> Developer -> Edit Config, then add:
```json
{
"mcpServers": {
"banimode": { "command": "uvx", "args": ["banimode-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": {
"banimode": { "type": "stdio", "command": "uvx", "args": ["banimode-mcp"] }
}
}
```
</details>
<details>
<summary><b>Codex CLI</b></summary>
```bash
codex mcp add banimode -- uvx banimode-mcp
```
Or in `~/.codex/config.toml`:
```toml
[mcp_servers.banimode]
command = "uvx"
args = ["banimode-mcp"]
```
</details>
<details>
<summary><b>Gemini CLI</b></summary>
Add to `~/.gemini/settings.json`:
```json
{
"mcpServers": {
"banimode": { "command": "uvx", "args": ["banimode-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 is a standard stdio MCP server: run `uvx banimode-mcp`, or `pip install banimode-mcp` and run `banimode-mcp`.
</details>
## Tools
| Tool | What it does |
|---|---|
| `bm_search` | Search Banimode fashion products by keyword and return priced cards with discount, color and sizes in stock. Sort, price range, size, in-stock, category and brand filters. |
| `bm_browse` | List the products of a category and/or brand (ids from `bm_categories` / `bm_brands`), with the same filters and cards as `bm_search`. |
| `bm_categories` | Find category ids by name, or walk the tree: no arguments lists the top sections, `parent_id` lists children. |
| `bm_brands` | Find brand ids by name (Persian or Latin), or list the first brands when no name is given. |
| `bm_deals` | List today's flash-sale products (deep time-limited discounts) with the time left. |
| `bm_product` | Get one product: every color with its price, discount, stock per size, features and short description. |
| `bm_reviews` | Read customer reviews of a product: stars (1-5, null if only text), text, date and the shop's answer. |
## Good to know
- **Prices are in Toman.** The API uses Rial; the server divides by 10 so numbers match the website.
- **One card per color.** The same product id can appear several times in a list; call `bm_product` for all colors and sizes.
- **Sold-out items are hidden by default** (`in_stock` is true), because sorting by price otherwise starts with unavailable items.
- **Persian queries match best** (`مانتو مجلسی`, `کفش اسپرت مردانه`).
- **Results are capped at 10,000 per query**, and a page holds at most 50 products (default 20, to keep answers small).
- **Flash-sale prices are time limited**; the tool returns the minutes left.
- **Shipping fee is not included.** It is only shown at checkout, so the real cost is `final_price` plus an unknown shipping fee.
- **Review and description text comes from the site and its users**; the server tells the agent to treat it as data, not instructions.
- **Not supported:** login, cart, orders, wishlist, wallet, posting reviews.
- **Proxy:** system proxy variables are ignored on purpose; set `BANIMODE_MCP_PROXY` if you need one.
## FAQ
<details>
<summary><b>Is there a Banimode API or MCP server for AI agents?</b></summary>
Yes: `banimode-mcp` is an unofficial MCP server with 7 read-only tools for search, categories, brands, flash sales, product details and reviews.
It calls the same JSON API the banimode.com site uses; no API key is needed.
</details>
<details>
<summary><b>How do I use Banimode with Claude, Cursor or Copilot?</b></summary>
Add the server with `claude mcp add banimode -- uvx banimode-mcp` (or the matching config in [Quick start](#quick-start)), then ask in plain language, in Persian or English.
</details>
<details>
<summary><b>Is it official, safe and free?</b></summary>
It is unofficial and not affiliated with Banimode. It is read-only (no login, cart or orders), runs on your machine and is free for non-commercial use.
</details>
<details>
<summary><b>Are prices in Toman?</b></summary>
Yes. The site's API uses Rial; this server converts to Toman.
</details>
<details>
<summary><b>Why does the same product appear twice?</b></summary>
Each search card is one color of a product. `bm_product` shows all colors with stock per size.
</details>
<details>
<summary><b>Can it buy something for me?</b></summary>
No, and that is deliberate. There is no login and no cart or checkout call. The agent finds the best option; you order on the site.
</details>
<details>
<summary><b>Do I need an Iranian IP?</b></summary>
No: the API answered directly from Iran and through a foreign (Turkish) proxy in testing, and there was no bot challenge. If your network needs a proxy, set `BANIMODE_MCP_PROXY`.
</details>
<details>
<summary><b>Does it show the shipping fee?</b></summary>
No. Banimode shows shipping only at checkout, so the tools return product prices without shipping.
</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>
## Configuration
| Variable | Default | Meaning |
|---|---|---|
| `BANIMODE_MCP_PROXY` | unset | Optional HTTP proxy URL, or a comma-separated list tried in turn, for banimode.com. System proxies are ignored. |
<a id="فارسی"></a>
## فارسی: سرور MCP بانی‌مد
<div dir="rtl">
**banimode-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای بانی‌مد (banimode.com)، فروشگاه اینترنتی مد و پوشاک در ایران، است.
این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در بانی‌مد لباس، کفش، کیف و اکسسوری جستجو کند،
قیمت‌ها را به تومان مقایسه کند، موجودی هر سایز را ببیند، نظرات خریداران را بخواند و تخفیف‌های فوری را پیدا کند.
**چه کارهایی می‌کند**
- جستجوی کالا با مرتب‌سازی (ارزان‌ترین، گران‌ترین، بیشترین تخفیف، جدیدترین) و فیلتر محدوده قیمت، سایز، موجودی، دسته و برند.
- مرور یک دسته یا برند، و پیدا کردن شناسه دسته‌ها و برندها.
- جزئیات کالا: همه رنگ‌ها با قیمت، تخفیف، موجودی هر سایز، ویژگی‌ها و توضیح کوتاه.
- نظرات خریداران با ستاره، متن، تاریخ و پاسخ فروشگاه.
- تخفیف‌های فوری امروز با زمان باقی‌مانده.
**نکته‌ها**
- فقط خواندنی است: وارد حساب نمی‌شود، سبد خرید نمی‌سازد و سفارش ثبت نمی‌کند.
- همه قیمت‌ها به تومان است. هزینه ارسال فقط هنگام پرداخت در سایت مشخص می‌شود و در نتیجه‌ها نیست.
- جستجوی فارسی بهترین نتیجه را می‌دهد.
- روی سیستم خود شما اجرا می‌شود و کلید API لازم ندارد.
**نصب** (اول [uv](https://docs.astral.sh/uv/getting-started/installation/) را نصب کنید). در Claude Code:
</div>
```bash
claude mcp add banimode -- uvx banimode-mcp
```
<div dir="rtl">
در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش [Quick start](#quick-start) را بگذارید.
**نمونه پرسش‌ها**
- «مانتو مجلسی زنانه زیر ۳ میلیون تومان در بانی‌مد پیدا کن.»
- «ارزان‌ترین کفش اسپرت مردانه سایز ۴۳ که موجود باشد کدام است؟»
- «تخفیف‌های فوری امروز بانی‌مد را نشان بده.»
**کلیدواژه‌ها:** بانی مد، بانی‌مد، خرید لباس آنلاین، فروشگاه اینترنتی مد و پوشاک، مانتو، کفش، کیف، قیمت لباس، تخفیف فوری، سرور MCP، هوش مصنوعی.
</div>
## Development
```bash
git clone https://github.com/sepehr071/banimode-mcp && cd banimode-mcp
uv sync
uv run python -m pytest # offline, against recorded responses
uv run python -m pytest -m live # real API
uv run ruff check .
```
Tools live in `src/banimode_mcp/catalog.py` and `product.py`; each is a typed async function with a docstring that tells the agent when to use it.
Issues and PRs are welcome.
Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions 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
- [Digikala MCP server](https://github.com/sepehr071/digikala-mcp) for Iran's largest online store
- [Khanoumi MCP server](https://github.com/sepehr071/khanoumi-mcp) for beauty and personal care
- [Torob MCP server](https://github.com/sepehr071/torob-mcp) for price comparison across shops
- [Shopino MCP server](https://github.com/sepehr071/shopino-mcp) for fashion shopping
- [Basalam MCP server](https://github.com/sepehr071/basalam-mcp) for a marketplace of independent sellers
- Listed on [mcpfarsi.ir](https://mcpfarsi.ir/servers/banimode/), the Persian MCP marketplace
## Disclaimer
Unofficial and not affiliated with or endorsed by Banimode. It uses the open JSON API of the banimode.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) یا [گیت‌هاب](https://github.com/sepehr071) با سپهر رادمرد تماس بگیرید. متن کامل: [PolyForm Noncommercial 1.0.0](https://github.com/sepehr071/banimode-mcp/blob/main/LICENSE). نسخه‌های پیش از 0.2.1 با مجوز MIT منتشر شده‌اند و همان مجوز را دارند.
Free for personal and non-commercial use under the [PolyForm Noncommercial License 1.0.0](https://github.com/sepehr071/banimode-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.2.1 were released under MIT and stay under it.
TDQS
Scored across 7 tools
Each tool maps to a distinct intent: keyword search, category/brand listing, taxonomy lookup, brand lookup, deals, product detail, and reviews. The only overlap is bm_search vs bm_browse, which return the same card shape and can both accept category/brand ids, but the descriptions clearly mark search as keyword-driven and browse as filter-driven.
All tools share a uniform bm_ prefix with a single lowercase token, giving a predictable namespace that is easy to scan. The second token mixes actions (search, browse) with resources (categories, brands, deals, product, reviews), a minor deviation from a strict verb_noun pattern but still coherent and readable.
Seven tools is well within the sweet spot and every one earns its place: discovery (search/browse/deals), resolution helpers (categories/brands), and detail pages (product/reviews). Nothing looks redundant or padded.
The discovery lifecycle is fully covered: find ids, list products, get detail, check reviews, check deals. Gaps are minor, such as no sorting/pagination control or explicit price/filter parameters beyond the card-level filters, but agents can work around these via browse and product calls.