Basalam

AI エージェント向け

• 概要： Basalam（basalam.com）向けの非公式 MCP サーバー（モデルコンテキストプロトコル）です。イランの小規模ショップが集まるマーケットプレイスです。ペルシャ語での検索が最適です。価格はトマン表記です。
• インストール： 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 を使えば、エージェントは数回の呼び出しでこれを行えます。bs_find_cheapest（内容の乏しい安値はデフォルトで非表示）、bs_product、bs_vendor、bs_reviews を使います。

できること

• 商品を検索できます。価格帯（トマン）、カテゴリ、送料無料、割引、人気ショップ、分割払いのフィルターを指定し、関連度、販売数、価格、新着順で並べ替えられます。
• 在庫のある最安値の商品を検索できます。最低価格と、任意の最低評価を指定できます。
• 商品を1件確認できます。価格、割引、在庫、販売数、送料無料の条件、オプション（サイズ、カラー）、属性、評価、販売ショップを確認できます。
• ショップを確認できます。所在地、営業状況、商品数、配送方法を確認し、商品を閲覧または検索できます。
• カテゴリを閲覧できます。カテゴリツリー全体、カテゴリの子カテゴリ、名前による検索に対応しています。IDはcategory_idフィルターに使用できます。
• レビューを確認できます。商品のレビューと、商品およびショップの星評価の分布を確認できます。
• 読み取り専用として設計されています。ログイン、カート、注文には対応していません。

プロンプトの例：

• 「Basalamで、星4つ以上の手織りウールラグの最安値は？」
• 「送料無料で50万トマン未満のサフランを、人気商品順に探して。」
• 「このショップは信頼できますか？プロフィール、新着商品、最新のレビューを表示して。」
• 「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を返すため、エージェントのコンテキストを大量に消費しません。

仕組み

  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キーも不要で、お客様に関する情報がほかの場所に送信されることもありません。許可されているのは、これら2つのBasalamホストのみです。

知っておくと便利なこと

• 価格の単位はトマンです。 Basalam API はリアルで応答しますが、各ツールで 10 で割り（価格フィルターは 10 倍するため）、ウェブサイトと同じ数値になります。
• 評価は 0～5 です。 評価がない場合は、未評価を意味します。
• ペルシャ語のクエリが最もよく一致します。
• 検索結果の合計は 10000 件で上限になります（検索インデックスの上限です）。応答を小さく保つため、各ページには最大 30 商品が表示されます。ページの件数が少ない場合は、後続の行から補充されるため、隣接するページに同じ商品がいくつか重複して表示されることがあります。
• 「最安値」順には、数百トマンの水増し出品が多数含まれます。 bs_find_cheapest はデフォルトで 5000 トマン未満の価格を非表示にします（min_price）。
• 商品の販売数と送料無料のしきい値は、商品ページで使われる追加の 2 回の呼び出しで取得します。どちらかが失敗した場合、その項目は単に欠落します。
• 日付と時刻は、Basalam が返す形式のまま渡されます（イランの現地時間で、変換されません）。
• レビュー、商品説明、ショップのテキストはユーザーが作成した内容で、full_text=true を指定しない限り 400 文字で切り詰められます。
• 公開されない情報： ベンダー API 独自の score（常に 0 です。bs_reviews のショップ評価を使用してください）と、評価および同一都市での検索フィルターです。
• 次の操作は行いません。 ログイン、カートへの追加、注文、ショップとのチャット、レビューの投稿。
• 応答は 60 秒間キャッシュされます。 タイムアウト、5xx、429 の場合は再試行します。

FAQ

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 にあります。それぞれ、エージェントが使用するタイミングを説明する docstring を備えた、型付けされた非同期関数です。問題の報告や PR を歓迎します。特に、新しいツールや API 変更への修正を歓迎します。

リリースするには、pyproject.toml と server.json のバージョンを更新し、v* タグをプッシュします。GitHub Actions がテストを実行し、PyPI と MCP Registry に公開して、GitHub Release を作成します。

関連サーバー

• iran-mcp：イランの各種サービス向け MCP サーバーのカタログ
• Digikala MCP server：イラン最大のオンラインストア向け
• Torob MCP server：イランのショップ間での価格比較向け
• Technolife MCP server：電子機器の価格向け
• Banimode MCP server：ファッション向け
• Divar MCP server：クラシファイド広告向け

免責事項

非公式であり、Basalam との提携や承認はありません。basalam.com のウェブアプリが公開しているエンドポイントを使用しており、予告なく変更される場合があります。リクエスト頻度は適切に抑えてください。

作者

Sepehr Radmard（سپهر رادمرد）が開発・保守しています。LinkedIn でつながるか、GitHub の @sepehr071 をフォローすると、イランのウェブサイト向け MCP サーバーを確認できます。すべて iran-mcp に掲載されています。このプロジェクトが時間の節約に役立ったら、リポジトリにスターを付けていただけると、ほかの人にも見つけてもらいやすくなります。

ライセンス

MIT