Banimode

banimode-mcp: Banimode MCP server for AI agents

Let your AI agent shop for fashion on Banimode (بانی‌مد).
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.

[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 · 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 (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 and the iran-mcp catalog (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."
• مانتو مجلسی زنانه زیر ۳ میلیون تومان در بانی‌مد پیدا کن.
• ارزان‌ترین کفش اسپرت مردانه سایز ۴۳ که موجود باشد کدام است؟
• تخفیف‌های فوری امروز بانی‌مد را نشان بده.

Quick start

You need uv. No API key or account.

claude mcp add banimode -- uvx banimode-mcp

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

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

codex mcp add banimode -- uvx banimode-mcp

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

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

Tools

How it works

  AI agent  (Claude, Cursor, Copilot, ...)      │      │  MCP over stdio      ▼  banimode-mcp  (runs on your machine)      │      │  HTTPS      └──────▶  mobapi.banimode.com   products, categories, brands, deals, reviews

banimode-mcp runs locally and calls the open JSON API that the banimode.com website itself uses. There is no hosted server in between and no API key. Requests are throttled and retried on timeouts, 429 and 5xx.

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

Configuration

فارسی: سرور MCP بانی‌مد

claude mcp add banimode -- uvx banimode-mcp

Development

git clone https://github.com/sepehr071/banimode-mcp && cd banimode-mcpuv syncuv run python -m pytest            # offline, against recorded responsesuv run python -m pytest -m live    # real APIuv 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 and creates the GitHub Release.

Related servers

• iran-mcp: catalog of all Iranian-service MCP servers
• Digikala MCP server for Iran's largest online store
• Khanoumi MCP server for beauty and personal care
• Torob MCP server for price comparison across shops
• Shopino MCP server for fashion shopping
• Basalam MCP server for a marketplace of independent sellers
• Listed on mcpfarsi.ir, 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

[Sepehr Radmard: open-source MCP servers for the Iranian web. LinkedIn: linkedin.com/in/sepehr-radmard]

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