basalam-mcp
Advanced tools
Unofficial read-only MCP server for Basalam: search marketplace products, find the cheapest offers, read shops, categories and reviews.
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 · فارسی
uvx basalam-mcp or claude mcp add basalam -- uvx basalam-mcp. Transport: stdio. Needs uv (Python 3.10+).BASALAM_MCP_PROXY (HTTP proxy URL, or a comma-separated list).bs_. Start with bs_search or bs_find_cheapest. Typical sequence: bs_find_cheapest -> bs_product -> bs_reviews.https://basalam.com/p/<id>.server.json and the
iran-mcp catalog (TOOLS.md, servers.json, llms.txt).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.
category_id filterExample prompts:
You need uv. No API key or account.
claude mcp add basalam -- uvx basalam-mcp
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"basalam": { "command": "uvx", "args": ["basalam-mcp"] }
}
}
Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code above, or add to .vscode/mcp.json:
{
"servers": {
"basalam": { "type": "stdio", "command": "uvx", "args": ["basalam-mcp"] }
}
}
codex mcp add basalam -- uvx basalam-mcp
Or in ~/.codex/config.toml:
[mcp_servers.basalam]
command = "uvx"
args = ["basalam-mcp"]
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"basalam": { "command": "uvx", "args": ["basalam-mcp"] }
}
}
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It's a standard stdio MCP server: run uvx basalam-mcp, or pip install basalam-mcp and run basalam-mcp.
All 7 tools are annotated readOnlyHint: true and return compact JSON, so they don't flood the agent's context.
| Tool | What it does |
|---|---|
bs_search | Search Basalam products and return a page of cards with prices in Toman. |
bs_find_cheapest | List the cheapest in-stock offers for a query, cheapest first, prices in Toman. |
bs_categories | Browse Basalam's category tree and return ids for the category_id filter of bs_search. |
bs_product | Get one product: price in Toman, discount, stock, options (colors, sizes), attributes, rating and its shop. |
bs_vendor | Get a Basalam shop's profile: city, product count, shipping methods, activity and notice. |
bs_vendor_products | List one shop's products with prices in Toman, searchable and sortable. |
bs_reviews | Read customer reviews of a product with the star histogram, newest first. |
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.
bs_find_cheapest hides prices under 5000 Toman by default (min_price).full_text=true.score (always 0; use the shop stars from bs_reviews), and the rating and same-city search filters.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.
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.
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.
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.
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.
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.
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.
uvx is not foundUse the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
npx @modelcontextprotocol/inspector uvx basalam-mcp
| Variable | Default | Meaning |
|---|---|---|
BASALAM_MCP_PROXY | unset | Optional HTTP proxy URL; system proxy settings are ignored. Also accepts a comma-separated list: one is used until it gets blocked or fails to connect, then the next |
basalam-mcp یک سرور MCP غیررسمی و فقطخواندنی برای باسلام، بازار آنلاین کسبوکارهای کوچک و غرفهداران ایرانی، است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد در باسلام جستجو کند، ارزانترین پیشنهادها را پیدا کند و محصول، غرفه، دستهبندی و نظر خریداران را بخواند.
چه کارهایی میکند
نکتهها
نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add basalam -- uvx basalam-mcp
در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسشها
کلمات کلیدی: باسلام، خرید آنلاین از باسلام، بازار آنلاین کسبوکارهای کوچک، مقایسه قیمت، ارزانترین قیمت، غرفه، صنایع دستی، سرور MCP، هوش مصنوعی.
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.
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.
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.
FAQs
Unofficial read-only MCP server for Basalam: search marketplace products, find the cheapest offers, read shops, categories and reviews.
We found that basalam-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.