Okala

目次

AI エージェント向け · 概要 · できること · クイックスタート · ツール · 仕組み · 知っておくとよいこと · ログイン（任意） · FAQ · 設定 · فارسی · 開発 · 関連サーバー · 免責事項 · ライセンス

AI エージェント向け

• 概要： Okala（okala.com、اُکالا）向けの非公式 MCP サーバー（model context protocol）です。Okala は、地域のスーパーマーケット、パン屋、果物店、チェーン店が住所まで配達するイランのオンライン食料品マーケットプレイスです。ペルシャ語での検索が最適です。価格はトマンです。
• インストール： uvx okala-mcp または claude mcp add okala -- uvx okala-mcp。トランスポート：stdio。uv（Python 3.10+）が必要です。
• 認証： 不要です。任意の SMS ログイン（ok_login）を行うと、Okala のテキスト検索を ok_search で利用できます。環境変数：OKALA_MCP_PROXY（HTTP プロキシ）、OKALA_MCP_TOKEN（保存済みのログインの代わりに使うアクセストークン）、OKALA_MCP_TOKEN_FILE（ログイン情報の保存先）。
• アクセス： 買い物用の 12 個のツールは読み取り専用です。カート、注文、支払い、レビュー用のツールはありません。ログイン用の 4 個のツールはユーザー自身のログインに作用します。ok_login はユーザーの電話番号に SMS を送信し、ok_login_verify はログイン情報を保存し、ok_logout はログイン情報を削除します。ok_login または ok_logout を呼び出す前にユーザーに確認してください。ユーザーから依頼されない限りログインしないでください。また、トークンを尋ねたり、繰り返し伝えたりしないでください。
• ツール： 16 個で、すべて ok_ で始まります。位置情報を使うすべてのツールには lat と lon が必要なので、まず ok_locate を使ってください。一般的な手順：ok_locate → ok_search → ok_compare、または ok_locate → ok_stores → ok_store_products。
• 利用する場面： 住所に配達可能な店舗の確認、近隣店舗間での商品の価格や手数料の比較、配達時間帯、最低注文金額、本日の特売の確認。
• 利用しない場面： ユーザーが注文を希望している場合（カートやチェックアウト機能はありません）、または Okala の配達エリア外（テヘランおよびその他一部の大都市）にいる場合。
• 出力： コンパクトな JSON。価格はトマンです（API のリアルを 10 で割った値）。final_price は購入者が支払う金額、price は割引前の価格、discount_pct は整数の割引率、評価は 0～5 です。ツール間で ok_locate の lat と lon、および ok_stores の store_id を渡してください。
• 機械可読データ： server.json、およびイランの全 MCP サーバーのカタログ iran-mcp（TOOLS.md、servers.json、llms.txt）。

理由

Okala では、同じ牛乳パックでも店舗ごとに価格が異なり、サービス料や梱包料、最低注文金額も店舗ごとに設定されています。サイトでは一度に 1 店舗しか表示されず、ログインしないと検索ボックスも使えません。okala-mcp を使うエージェントなら、配達可能なすべての店舗を一度に確認できます。

あなた： テヘランのユセフアーバード近辺で、カレの無乳糖牛乳が一番安いのはどこですか？

エージェント： 呼び出し ok_locate(address="یوسف آباد") → ok_search(query="شیر بدون لاکتوز کاله", ...) → ok_compare(category_slug="low-fat-milk", ...)

カレの無脂肪・無乳糖牛乳（1 L）は、近隣の営業中の店舗 17 店で販売されています。最安値はیاران دریان گلریزの 147,875 トマン（169,000 トマンから 12% 割引）で、距離は 1.6 km、本日の最初の配達枠は 08-09 です。サービス料 10,500 トマンと梱包料 3,000 トマンが別途かかります。 最も高い店舗では 180,000 トマンなので、32,125 トマン節約できます。

_{2026-10-07 の実際のツール出力です。価格は常に変動します。価格はトマンです。}

すべての返信はコンパクトな JSON テキストブロックなので、エージェントのコンテキストを圧迫しません。

できること

• 住所を検索（ペルシャ語）し、そこに配達する店舗を評価、距離、最初の配達枠、手数料とともに一覧表示します
• 近くの商品を検索：名前で検索します。オプションの初回ログイン後はOkala独自のテキスト検索を使用し、それ以外の場合はOkalaのカテゴリーから照合します
• 比較：近くのすべての店舗で同じ商品を比較します。最安の店舗から順に、各店舗の手数料も表示します
• 1店舗を閲覧：部門全体を価格順または割引順に並べ、名前で絞り込みます
• 商品詳細：価格、割引、在庫、注文あたりの上限数、ブランド、画像
• 店舗詳細：最低注文金額、現在お客様の住所に配達可能かどうか、その日のすべての配達枠、カスタマーレビュー
• お得情報：近くまたは1店舗の本日のお得情報一覧、および店舗の最大割引
• 設計上、買い物に関する書き込みは行いません：カート、注文、レビュー投稿はありません（オプションのログインは検索にのみ使用します）

プロンプトの例：

• 「ヴァナク広場の近くで1時間以内に配達できるスーパーマーケットと、配達手数料を教えてください。」
• 「近くで最も安いカレの全脂肪牛乳はどこですか？また、その店舗の最低注文金額は牛乳1パックの購入で問題になりますか？」
• 「店舗11009の今日のお得情報は何ですか？」
• 「テヘランのサーデギーイェ近くで、店舗ごとに米1 kgの価格を比較してください。」
• アルゼンチン広場近くで最も安いツナ缶を扱う店舗はどこですか？
• ヴァナク近くで現在配達を行っているオカラのスーパーマーケットはどこですか？配達手数料はいくらですか？
• ヨセフ・アーバード近くの店舗で今日の割引を表示してください。

クイックスタート

uvが必要です。APIキーやアカウントは不要です。

claude mcp add okala -- uvx okala-mcp

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

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

codex mcp add okala -- uvx okala-mcp

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

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

まず ok_locate を使います。位置情報を扱う各ツールにはここで取得した lat と lon を渡し、store_id は ok_stores から取得します。

12 個のショッピングツールと ok_account には readOnlyHint: true が付いています。ok_login、ok_login_verify、ok_logout には付いていません （SMS を送信するか、保存済みのログイン情報を変更するため）。そのため、クライアントは実行前に確認を求めます。ok_logout には destructiveHint: true も付いています。ログインコードは 1 時間あたり最大 3 件まで送信できます。

仕組み

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  okala-mcp  (runs on your machine)
      │
      │  HTTPS
      └──────▶  apigateway.okala.com   the JSON API behind okala.com

okala-mcp はローカルで動作し、ログインしない限りゲストとして、okala.com のウェブサイトと同じエンドポイントを呼び出します。 間にホスト型サーバーはなく、API キーも不要です。また、あなたに関する情報がほかの場所に送信されることもありません （Okala に送信されるのは、問い合わせた配送地点だけです）。リクエストは Chrome を装うクライアント経由で送信され、同時に処理されるのは最大 2 件で、少しのジッターが加わります。失敗した GET リクエストは最大 2 回再試行されます。

知っておくと便利なこと

• 価格はトマン建てです。 API はリアル建てで返すため、すべてのツールで 10 で割ります。final_price は実際に支払う価格、price は割引前の価格、discount_pct は整数の割引率です。
• 店舗ごとに価格が異なります。 商品 ID はどの店舗でも同じ商品を示すため、ok_compare で価格を並べて比較できます。
• 1 店舗での注文費用は、商品代金＋サービス料＋梱包料＋配送料（ok_stores）です。また、かごの合計は店舗のminimum_order（ok_store）以上である必要があります。1 つのかごで注文できるのは 1 店舗のみです。
• テキスト検索にはログインが必要です。 Okala で検索できるのはログイン済みユーザーのみです。一度ログインすると（ログイン（任意）を参照）、ok_search で Okala の実際の検索機能を使い、現在地の近く、または 1 店舗内（store_id）でブランドや商品名も検索できます（نوتلا）。ゲストの場合、ok_search は入力語をカテゴリー名に照合し（شیر → 牛乳）、商品を名前で並べ替えます。1 店舗の商品を検索するには、name_contains を指定したok_store_productsを使うと、その部門全体を取得できます。
• 店舗横断リストで返される商品は、店舗ごとに最大 12 件です。より正確に比較するには、カテゴリーのスラッグを絞り込むか、ブランド ID を指定してください。
• ペルシャ語が最適です（شیر کم چرب、پنیر、تن ماهی）。アラビア語の ي / ك と半角スペースは正規化されます。
• 営業時間外の店舗はok_searchとok_compareの結果から除外されます。open_only: falseを指定したok_storesでは、現在閉店中の店舗も表示されます。
• 時刻： 配達時間枠と日付はテヘランの現地時間、セール終了時刻は UTC です。
• クーポンバッジ： 商品にkalabargバッジが付いている場合、政府発行のクーポンで支払えます。
• ブランド： 公開リストに掲載されているのは、一部の注目ブランドのみです。ok_brandsではスラッグを使ってほかのブランドも検索できます。
• 対応していないこと： カート、チェックアウト、注文、支払い、買い物リスト、レビュー投稿、サポートチケットには対応していません。また、既定の位置情報はないため、必ずlatとlonを渡してください。Okala は予告なく API を変更することがあるため、リクエスト頻度は適切に保ってください。

ログイン（任意）

すべての機能はゲストのままでも使えます。ログインすると、ok_searchで Okala のテキスト検索（ブランド名や商品名の検索。1 店舗内での検索も含む）が使えるようになります。エージェントに次のように頼むだけです。

あなた： Okala にログインしてください。電話番号は 0912 123 4567 です

エージェント： ok_loginを呼び出します → Okala から SMS が届きます → コードを入力します（クライアントにフォームが表示される場合はそのフォームに、表示されない場合はチャットに入力します）→ ログイン完了

• コードはリクエストした場合にのみ送信され、同じ番号には 2 分に 1 回まで送信できます。
• クライアントが MCP フォーム（エリシテーション）に対応している場合、コードはサーバーに直接送られ、モデルを経由しません。
• ログイン情報はお使いのマシン（~/.okala-mcp/token.json）に保存され、自動で更新されます。apigateway.okala.comにのみ送信され、ツールの応答に表示されることはありません。ログインが機能しなくなった場合、サーバーはゲストとして動作を続けます。
• ok_accountで状態を確認でき、ok_logoutでログイン情報を削除できます。

ターミナルを使いたい場合も、コマンドラインから同じようにログインできます。

uvx okala-mcp login 09121234567          # sends the code
uvx okala-mcp login 09121234567 12345    # saves the login
uvx okala-mcp logout                     # deletes it

コマンドラインからログインした後は、MCP クライアントを再起動してください（実行中のサーバーは起動時に一度だけログイン情報を読み込みます）。

よくある質問

npx @modelcontextprotocol/inspector uvx okala-mcp

設定

ペルシア語：Okala MCP サーバー

claude mcp add okala -- uvx okala-mcp

開発

git clone https://github.com/sepehr071/okala-mcp && cd okala-mcp
uv sync
uv run pytest            # offline, against recorded responses
uv run pytest -m live    # real okala.com
uv run ruff check .

ツールは src/okala_mcp/stores.py、catalog.py、offers.py、account.py にあります。それぞれ型が指定された非同期関数で、エージェントがいつ使用すべきかを説明する docstring が付いています。新しいツールの追加やサイトの変更への対応など、Issue や PR を歓迎します。

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

関連サーバー

• iran-mcp：イランのサービス向け MCP サーバーのカタログ
• snapp-mcp：Snappfood と SnappMarket の料理や食料品の価格
• tapsifood-mcp：Tapsi Food のレストランと料理の配達
• digikala-mcp：Digikala の商品検索と価格
• torob-mcp：Torob でイランのショップ間の価格を比較

クリック数の削減に役立ったら、スターを付けていただけると、ほかの人にも見つけてもらいやすくなります。

免責事項

非公式のプロジェクトであり、Okala との提携や、Okala による推奨を受けたものではありません。okala.com ウェブサイトのエンドポイントを使用しており、予告なく変更される場合があります。リクエスト頻度は適切な範囲に抑えてください。

作者

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

ライセンス

MIT