Basalam

basalam-mcp: Basalam MCP server for AI agents

Let your AI agent shop on Basalam (باسلام).

An unofficial, read-only MCP server for Basalam, Iran's marketplace of independent shops:

search products, find the cheapest in-stock offers, read shops, categories and customer reviews, all from Claude, Cursor or Copilot.

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

For AI agents

• What: unofficial MCP server (model context protocol) for Basalam (basalam.com), Iran's marketplace of small shops. Persian queries match best; prices in Toman.
• Install: uvx basalam-mcp or claude mcp add basalam -- uvx basalam-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional BASALAM_MCP_PROXY (HTTP proxy URL, or a comma-separated list).
• Access: read-only. No login, basket, order, chat or review posting, so no confirmation is needed before calling any tool.
• Tools: 7, all prefixed bs_. Start with bs_search or bs_find_cheapest. Typical sequence: bs_find_cheapest -> bs_product -> bs_reviews.
• Use when: finding, comparing or judging products, prices, shops and reviews on Basalam.
• Do not use when: the user wants to buy something or needs anything behind a login.
• Output: compact JSON. Prices in Toman (the API reports Rial; converted), ratings 0-5, null and empty fields omitted. A product link is https://basalam.com/p/<id>.
• Machine-readable: server.json and the iran-mcp catalog (TOOLS.md, servers.json, llms.txt).

Why

Basalam is a marketplace of thousands of small shops, so the same kind of item is listed many times at very different prices, and a plain "cheapest first" sort is full of filler listings priced at a few hundred Toman. Finding the real cheapest offer, then checking the product options, the shop and what buyers say, takes a lot of clicking. With basalam-mcp an agent does it in a few calls: bs_find_cheapest (filler prices hidden by default), bs_product, bs_vendor and bs_reviews.

What it can do

• Search products with price range (Toman), category, free shipping, discount, top-shop and installment filters, sorted by relevance, sales, price or newest
• Find the cheapest in-stock offers for a query, with a price floor and an optional minimum rating
• Read one product: price, discount, stock, sales count, free-shipping threshold, options (sizes, colors), attributes, rating and its shop
• Check a shop: city, activity, product count, shipping methods, and browse or search its products
• Browse categories: the whole tree, children of a category, or search by name; ids feed the category_id filter
• Read reviews with the star histogram of the product and its shop
• Read-only by design: no login, no basket, no orders

Example prompts:

• "Cheapest handmade wool rug on Basalam with at least 4 stars?"
• "Find saffron under 500,000 Toman with free shipping, best sellers first."
• "Is this shop reliable? Show its profile, its newest products and the latest reviews."
• "List the sub-categories of home decor on Basalam."
• ارزان‌ترین زعفران نگین با ارسال رایگان در باسلام کدام است؟
• نظر خریداران درباره این محصول را بخوان و بگو ایرادش چیست.

Quick start

You need uv. No API key or account.

Claude Code

claude mcp add basalam -- uvx basalam-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

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

Cursor

Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

VS Code (Copilot agent mode)

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

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

Codex CLI

codex mcp add basalam -- uvx basalam-mcp

Or in ~/.codex/config.toml:

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

Gemini CLI

Add to ~/.gemini/settings.json:

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

Windsurf

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

Anything else

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

Tools

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

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  basalam-mcp  (runs on your machine)
      │
      │  HTTPS
      └──────▶  services.basalam.com, core.basalam.com   search, products, shops, reviews

basalam-mcp runs locally and calls the same public endpoints the basalam.com web app uses. There is no hosted server in between, no API key, and nothing about you is sent anywhere else. Only those two Basalam hosts are allowed.

Good to know

• Prices are in Toman. The Basalam API answers in Rial; every tool divides by 10 (and price filters are multiplied by 10), so numbers match the website.
• Ratings are 0-5. A missing rating means not rated.
• Persian queries match best.
• Result totals stop at 10000 (the search index cap). Pages hold at most 30 products to keep replies small; a short page is refilled from the following rows, so neighbouring pages can repeat a few products.
• "Cheapest" sorts are full of filler listings priced at a few hundred Toman; bs_find_cheapest hides prices under 5000 Toman by default (min_price).
• Sales count and free-shipping threshold of a product are read with two extra calls the product page uses; if one fails, its fields are simply missing.
• Dates and times are passed through as Basalam returns them (Iran local time, not converted).
• Review, description and shop text is user-generated and cut to 400 characters unless full_text=true.
• Not exposed: the vendor API's own score (always 0; use the shop stars from bs_reviews), and the rating and same-city search filters.
• It does not log in, fill a basket, order, chat with shops or post reviews.
• Answers are cached for 60 seconds; a timeout, 5xx or 429 is retried.

FAQ

Is there a Basalam API or MCP server for AI agents?

Yes: basalam-mcp is an unofficial MCP server with 7 read-only tools for product search, cheapest offers, shops, categories and reviews. It calls the same public endpoints the basalam.com web app uses; no API key is needed.

How do I use Basalam with Claude, Cursor or Copilot?

Add the server with claude mcp add basalam -- uvx basalam-mcp (or the matching config in Quick start), then ask in plain language, in Persian or English.

Is it official, safe and free?

It is unofficial and not affiliated with Basalam. It is read-only (no login, basket or orders), runs on your machine, and is free under the MIT license.

Do I need an Iranian IP?

No. In testing (2026-10-19) Basalam answered both from a Turkish exit and directly. If your network blocks it, set BASALAM_MCP_PROXY to an HTTP proxy. Normal system proxy variables are ignored on purpose.

Can it buy something for me?

No, and that is deliberate. It has no login and only reads public data. The agent finds the best option; you buy it on the site.

Why are some prices missing or tiny?

Sorting by price puts filler listings at a few hundred Toman first. Use bs_find_cheapest, which hides prices under 5000 Toman by default; lower min_price if you really want them.

How do I filter by category?

Call bs_categories (with query to search by name, or parent_id to list children), then pass the id as category_id to bs_search.

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?

npx @modelcontextprotocol/inspector uvx basalam-mcp

Configuration

فارسی: سرور MCP باسلام

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

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

• جستجوی محصول با فیلتر بازه قیمت، دسته‌بندی، ارسال رایگان، تخفیف، غرفه‌های برتر و پرداخت اقساطی؛ مرتب‌سازی بر اساس مرتبط‌ترین، پرفروش‌ترین، قیمت یا جدیدترین.
• ارزان‌ترین پیشنهادهای موجود برای یک عبارت، با حداقل قیمت و حداقل امتیاز اختیاری.
• جزئیات محصول: قیمت، تخفیف، موجودی، تعداد فروش، حد ارسال رایگان، گزینه‌ها (رنگ و سایز)، ویژگی‌ها، امتیاز و غرفه‌دار.
• پروفایل غرفه: شهر، تعداد محصول، روش‌های ارسال و فهرست محصولات غرفه.
• درخت دسته‌بندی‌ها و جستجوی دسته با نام.
• نظرات خریداران همراه با نمودار ستاره‌ها.

نکته‌ها

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

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

claude mcp add basalam -- uvx basalam-mcp

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

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

• «ارزان‌ترین زعفران نگین در باسلام کدام است؟»
• «محصولات دست‌ساز با ارسال رایگان زیر ۵۰۰ هزار تومان را نشان بده.»
• «این غرفه قابل اعتماد است؟ نظرات خریداران را بخوان.»
• «زیردسته‌های دسته خانه و دکور را فهرست کن.»

کلمات کلیدی: باسلام، خرید آنلاین از باسلام، بازار آنلاین کسب‌وکارهای کوچک، مقایسه قیمت، ارزان‌ترین قیمت، غرفه، صنایع دستی، سرور MCP، هوش مصنوعی.

Development

git clone https://github.com/sepehr071/basalam-mcp && cd basalam-mcp
uv sync
uv run python -m pytest -q          # offline, against recorded responses
uv run python -m pytest -m live -q  # one live test per tool
uv run ruff check .

Tools live in src/basalam_mcp/catalog.py and shop.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 API 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

• iran-mcp: catalog of all Iranian-service MCP servers
• Digikala MCP server for Iran's largest online store
• Torob MCP server for price comparison across Iranian shops
• Technolife MCP server for electronics prices
• Banimode MCP server for fashion
• Divar MCP server for classified ads

Disclaimer

Unofficial and not affiliated with or endorsed by Basalam. It uses the public endpoints of the basalam.com web app, 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