Basalam

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 mcp add basalam -- uvx basalam-mcp

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

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

codex mcp add basalam -- uvx basalam-mcp

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

{  "mcpServers": {    "basalam": { "command": "uvx", "args": ["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

npx @modelcontextprotocol/inspector uvx basalam-mcp

Configuration

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

claude mcp add basalam -- uvx basalam-mcp

Development

git clone https://github.com/sepehr071/basalam-mcp && cd basalam-mcpuv syncuv run python -m pytest -q          # offline, against recorded responsesuv run python -m pytest -m live -q  # one live test per tooluv 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
• Listed on mcpfarsi.ir, the Persian MCP marketplace

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

[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