Basalam

面向 AI Agent

• 简介： 面向 Basalam（basalam.com）的非官方 MCP 服务（模型上下文协议）。Basalam 是伊朗的小型商铺集市。使用波斯语查询效果最佳；价格以托曼计。
• 安装： uvx basalam-mcp 或 claude mcp add basalam -- uvx basalam-mcp。传输方式：stdio。需要 uv（Python 3.10+）。
• 身份验证： 无需身份验证、API 密钥或账户。可选设置 BASALAM_MCP_PROXY（HTTP 代理 URL，或以逗号分隔的列表）。
• 访问权限： 只读。无需登录，无法操作购物篮、订单或聊天，也无法发布评价，因此调用任何工具前都无需确认。
• 工具： 共 7 个，名称均以 bs_ 开头。可从 bs_search 或 bs_find_cheapest 开始。典型调用顺序：bs_find_cheapest -> bs_product -> bs_reviews。
• 适用场景： 在 Basalam 上查找、比较或评估商品、价格、商铺和评价。
• 不适用场景： 用户想要购买商品，或需要访问任何登录后才能使用的内容。
• 输出： 精简的 JSON。价格以托曼计（API 返回里亚尔，已换算），评分范围为 0-5；省略 null 和空字段。商品链接格式为 https://basalam.com/p/<id>。
• 机器可读信息： server.json 和 iran-mcp 目录（TOOLS.md、servers.json、llms.txt）。

背景

Basalam 汇集了数千家小型商铺，因此同类商品会有许多条目，价格差异也很大；而直接按“价格从低到高”排序，结果中往往充斥着售价仅几百托曼的无关条目。找到真正的最低价商品，再查看商品选项、商铺信息和买家评价，需要反复点击。使用 basalam-mcp，Agent 只需调用几次工具即可完成：bs_find_cheapest（默认隐藏无关低价条目）、bs_product、bs_vendor 和 bs_reviews。

功能

• 搜索商品，可按价格范围（Toman）、类别、免运费、折扣、畅销店铺和分期付款筛选，并按相关性、销量、价格或上架时间排序
• 查找现货中最便宜的商品，支持设置最低价格和可选的最低评分
• 读取单个商品信息：价格、折扣、库存、销量、免运费门槛、选项（尺码、颜色）、属性、评分及所属店铺
• 查看店铺信息：城市、活跃状态、商品数量、配送方式，以及浏览或搜索其商品
• 浏览类别：完整类别树、某个类别的子类别，或按名称搜索；类别 ID 可用于 category_id 筛选
• 读取评价，包括商品及其店铺的星级分布
• 设计为只读：无需登录，不支持购物车或下单

提示词示例：

• “在 Basalam 上，至少 4 星的手工羊毛地毯哪款最便宜？”
• “找找 500,000 Toman 以下、免运费的藏红花，先显示畅销商品。”
• “这家店可靠吗？展示其资料、最新商品和最近的评价。”
• “列出 Basalam 家居装饰的子类别。”
• ارزان‌ترین زعفران نگین با ارسال رایگان در باسلام کدام است؟
• نظر خریداران درباره این محصول را بخوان و بگو ایرادش چیست.

快速开始

你需要 uv。无需 API 密钥或账户。

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"] }
  }
}

工具

所有 7 个工具均标注为 readOnlyHint: true，并返回精简的 JSON，因此不会占用 Agent 过多上下文。

工作原理

  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 在本地运行，并调用 basalam.com 网页应用使用的相同公共端点。中间没有托管 服务，无需 API 密钥，也不会将你的任何信息发送到其他地方。仅允许连接这两个 Basalam 主机。

需要了解的信息

• 价格单位为 Toman。 Basalam API 返回的价格单位为 Rial；每个工具都会除以 10（价格筛选值则乘以 10），因此数值与网站上的一致。
• 评分范围为 0-5。 缺少评分表示尚未评分。
• 使用波斯语查询效果最佳。
• 结果总数最高为 10000（搜索索引上限）。每页最多显示 30 件商品，以缩短回复；如果某页商品较少，会从后续行补入，因此相邻页面可能重复出现几件商品。
• 按“最便宜”排序的结果中，充斥着价格仅为几百 Toman 的填充商品；bs_find_cheapest 默认会隐藏价格低于 5000 Toman 的商品（min_price）。
• 商品销量和包邮门槛通过商品页面使用的另外两次请求读取；如果其中一次失败，相应字段就会缺失。
• 日期和时间会按 Basalam 返回的内容原样传递（伊朗当地时间，不进行转换）。
• 评价、描述和店铺文本由用户生成，除非设置 full_text=true，否则会截断至 400 个字符。
• **未提供：**供应商 API 自身的 score（始终为 0；请使用 bs_reviews 中的店铺星级），以及评分和同城搜索筛选条件。
• 它不会登录、添加商品到购物篮、下单、与店铺聊天或发布评价。
• 答案会缓存 60 秒；超时、5xx 或 429 响应会触发重试。

常见问题

npx @modelcontextprotocol/inspector uvx basalam-mcp

配置

波斯语：Basalam MCP 服务

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

工具位于 src/basalam_mcp/catalog.py 和 shop.py 中；每个工具都是带类型注解的异步函数，并附有说明何时使用该工具的文档字符串。欢迎提交问题和 PR，尤其是新增工具和修复 API 变更的兼容问题。

发布：在 pyproject.toml 和 server.json 中更新版本，然后推送一个 v* 标签。GitHub Actions 会运行测试、发布到 PyPI 和 MCP Registry，并创建 GitHub Release。

相关服务

• iran-mcp：伊朗各类服务的 MCP 服务目录
• 面向伊朗最大在线商店的 Digikala MCP 服务
• 用于比较伊朗各商店价格的 Torob MCP 服务
• 用于查询电子产品价格的 Technolife MCP 服务
• 面向时尚商品的 Banimode MCP 服务
• 用于分类广告的 Divar MCP 服务

免责声明

本项目为非官方项目，与 Basalam 无关联，也未获其认可。项目使用 basalam.com Web 应用的公开接口，这些接口可能随时变更，恕不另行通知。请合理控制请求频率。

作者

由 Sepehr Radmard（سپهر رادمرد）开发并维护。欢迎在 LinkedIn 上联系，或在 GitHub 上关注 @sepehr071，了解更多面向伊朗网站的 MCP 服务，所有服务均列于 iran-mcp。如果这个项目为您节省了时间，请在代码仓库点个星，帮助更多人发现它。

许可证

MIT