basalam-mcp: Basalam marketplace MCP server for AI agents
Let your AI agent shop on Basalam (باسلام). An unofficial, read-only MCP server for Iran's marketplace of independent shops: search products with price, category, shipping and discount filters, find the cheapest in-stock offers, read product details, shops, categories and customer reviews, all from Claude, Cursor or Copilot.
For AI agents
- What: unofficial MCP server for Basalam (basalam.com). Queries in Persian match best; prices in Toman.
- Install:
uvx basalam-mcporclaude mcp add basalam -- uvx basalam-mcp. Transport: stdio. Needs uv (Python 3.10+). - Auth: none, no API key or account. Basalam answers from non-Iranian IPs too.
- Optional env:
BASALAM_MCP_PROXY, an HTTP proxy URL (or a comma-separated list). System proxy settings are ignored on purpose. - Read-only: no login, basket, order, chat or review posting.
Quick start
claude mcp add basalam -- uvx basalam-mcp
Or in any MCP client config: {"command": "uvx", "args": ["basalam-mcp"]}.
Tools
| Tool | What it does |
|---|---|
bs_search |
Search products; filters: price range (Toman), category, free shipping, discount, top shops, installments; sort by relevance, sales, price, newest. |
bs_find_cheapest |
Cheapest in-stock offers for a query, cheapest first, with a price floor and optional minimum rating. |
bs_product |
One product: price, discount, stock, sales count, free-shipping threshold, options (sizes, colors), attributes, rating, shop. |
bs_vendor |
A shop's profile: city, activity, product count, shipping methods. |
bs_vendor_products |
One shop's products, searchable, filterable and sortable; an unknown shop is an error. |
bs_categories |
The category tree: top level, children of an id, or search by name (inside parent_id when both are given). Ids feed category_id. |
bs_reviews |
Customer reviews with the star histogram of the product and its shop. |
Notes
- Prices are Toman. The upstream API reports Rial; the server divides by 10.
- Result totals stop at 10000 (the search index cap). Pages hold at most 30 products (keeps each reply under 15 KB; a product's link is
https://basalam.com/p/<id>), and a short page is refilled from the following rows, so neighbouring pages can repeat a few products. - The cheapest sort is full of filler listings priced at a few hundred Toman;
bs_find_cheapesthides prices under 5000 Toman by default. - Dates and times are passed through as Basalam returns them (Iran local time, not converted; unconfirmed). The vendor API's own
scorefield is always 0, so it is not exposed; use the shop stars frombs_reviews. - Review and description text is user-generated and cut to 400 characters unless
full_text=true.
Development
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q # offline unit tests
uv run python -m pytest -m live -q # one live test per tool
uv build
Unofficial: not affiliated with Basalam. MIT License.
1 maintainer
Metadata
1 maintainer
Release files for basalam-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| basalam_mcp-0.1.0.tar.gz | 101.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| basalam_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 119.3 kB
Release files / basalam_mcp-0.1.0.tar.gz
| Download URL | basalam_mcp-0.1.0.tar.gz |
|---|---|
| Size | 101.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e508651ed413d585df9052449e87fab1a95f5caf19e96af92475e9d83d51af4f
|
|
BLAKE2b-256 checksum How to use checksums |
a78c3e1b3fbae40a14c4cd25689b8f0f9c7525a172494c0130db5cfdb6b933bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / basalam_mcp-0.1.0-py3-none-any.whl
| Download URL | basalam_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
301ff1c17d46ef8a6673fadd90b3909e782577646b1ec4b60b3a21d5721d52e5
|
|
BLAKE2b-256 checksum How to use checksums |
24ff84446ea59be400f26df6d5f3b05d3af6c5d9f314fea9944c17a29a2f1417
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for basalam-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for basalam_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
