Okala

目录

面向 AI Agent · 为什么 · 功能介绍 · 快速开始 · 工具 · 工作原理 · 须知 · 可选登录 · 常见问题 · 配置 · 波斯语 · 开发 · 相关服务 · 免责声明 · 许可证

面向 AI Agent

• 功能： Okala（okala.com，اُکالا）的非官方 MCP 服务（模型上下文协议）。Okala 是伊朗的在线杂货市场，当地超市、面包店、水果店和连锁店会配送到指定地址。使用波斯语查询效果最佳；价格单位为 Toman。
• 安装： 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，价格单位为 Toman（API 返回的 Rial 除以 10）。final_price 是买家实际支付的价格，price 是折扣前价格，discount_pct 是整数百分比，评分范围为 0-5。在不同工具之间传递 ok_locate 返回的 lat 和 lon，以及 ok_stores 返回的 store_id。
• 机器可读： server.json，以及 iran-mcp 中伊朗所有 MCP 服务的目录（TOOLS.md、servers.json、llms.txt）。

原因

在 Okala，同一箱牛奶在每家商店的价格都不同，而且每家商店还会收取自己的服务费和包装费，并设有各自的最低订单金额。网站一次只显示一家商店，而且不登录就无法使用搜索框。使用 okala-mcp 的 Agent 可以一次性查询所有能配送到你所在位置的商店：

你： 德黑兰尤塞夫阿巴德附近，哪里卖的 Kalleh 无乳糖牛奶最便宜？

Agent： 调用 ok_locate(address="یوسف آباد") → ok_search(query="شیر بدون لاکتوز کاله", ...) → ok_compare(category_slug="low-fat-milk", ...)

附近有 17 家营业中的商店在售 Kalleh 脱脂无乳糖牛奶（1 L）。最便宜的是 یاران دریان گلریز，售价 147,875 Toman（原价 169,000，折扣 12%），距离 1.6 km，今天最早的配送时段为 08-09，另加 10,500 服务费和 3,000 包装费。 最贵的商店售价为 180,000，因此你可以省下 32,125。

_{来自 2026-10-07 的真实工具输出；价格随时可能变化。价格单位为 Toman。}

每条回复都是紧凑的 JSON 文本块，因此不会让 Agent 的上下文充斥大量内容。

功能

• 定位一个地址（波斯语），并列出可配送到该地址的商店，以及评分、距离、最早时段和费用
• 查找附近的商品：按名称搜索；可选择性地登录一次后使用 Okala 自带的文本搜索，否则按 Okala 的分类匹配
• 比较附近所有商店中同一商品的价格，按价格从低到高排列，并显示每家商店的费用
• 浏览单家商店：查看一个完整商品部门，按价格或折扣排序，并按名称筛选
• 商品详情：价格、折扣、库存、每笔订单限购数量、品牌、图片
• 商店详情：最低订单金额、当前是否配送到你的地址、当天的所有配送时段、客户评价
• 优惠：查看附近商店或单家商店今日的优惠列表，以及某家商店的最大折扣
• 按设计不支持购物操作：不能添加购物车、下单或发布评价（可选登录仅用于搜索）

示例提示词：

• “瓦纳克广场附近哪些超市能在一小时内送达？配送费是多少？”
• “我附近最便宜的 Kalleh 全脂牛奶在哪里？如果只买一盒，该店的最低订单金额会不会成问题？”
• “11009 号商店今天有哪些优惠？”
• “比较德黑兰 Sadeghiyeh 附近各商店 1 千克大米的价格。”
• ارزان‌ترین تن ماهی نزدیک میدان آرژانتین کدام فروشگاه است؟
• کدام سوپرمارکت‌های اُکالا نزدیک ونک الان ارسال دارند و هزینه ارسالشان چقدر است؟
• تخفیف‌های امروز فروشگاه‌های نزدیک یوسف‌آباد را نشان بده.

快速开始

你需要 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 则不是（它们会发送短信或更改已保存的登录信息），因此客户端会在运行前征求你的同意；ok_logout 还标注为 destructiveHint: true。每小时最多发送 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 次。

需要了解

• 价格以 Toman 计价。 API 使用 Rial；每个工具都会除以 10。final_price 是实付价格，price 是折扣前价格，discount_pct 是整数百分比。
• 每家商店的价格都不同。 同一商品在每家商店的产品 ID 都相同，因此 ok_compare 可以将它们并列比较。
• 单家商店的订单费用 = 商品 + 服务费 + 包装费 + 配送费（ok_stores），且购物篮金额必须达到该商店的 minimum_order（ok_store）。一个购物篮只能对应一家商店。
• 文本搜索需要登录。 Okala 仅为已登录用户提供搜索。登录一次（见可选登录），ok_search 就会使用 Okala 的真实搜索功能，可搜索你附近的商品，也可在一家商店内搜索（store_id），包括品牌和商品名称（نوتلا）。作为访客，ok_search 会将你的搜索词匹配到类别名称（شیر → 牛奶），并按商品名称排序；若要在一家商店内搜索，可使用 ok_store_products 搭配 name_contains 来读取整个部门的商品。
• 跨店列表每家商店最多返回 12 件商品；使用更具体的类别 slug 或品牌 ID，可进行更精确的比较。
• 波斯语效果最佳（شیر کم چرب、پنیر、تن ماهی）。阿拉伯字母 ي / ك 和半空格都会标准化处理。
• ok_search 和 ok_compare 会排除已关闭的商店；使用 open_only: false 的 ok_stores 也会显示当前已关闭的商店。
• 时间： 配送时段和日期使用德黑兰当地时间；优惠结束时间为 UTC。
• 代金券标记： 商品上的 kalabarg 标记表示可以使用政府代金券支付。
• 品牌： 公开列出的仅有一小部分精选品牌；ok_brands 可以按 slug 查找其他品牌。
• 不支持的功能： 不支持购物车、结账、订单、付款、购物清单、发布评价或提交支持工单，也没有默认位置（始终传入 lat 和 lon）。Okala 可能会随时更改其 API，因此请合理控制请求频率。

可选登录

访客也能使用所有功能。登录仅会解锁 ok_search 中 Okala 的文本搜索（品牌和商品名称，也支持在一家商店内搜索）。只需让你的 Agent：

你： 帮我登录 Okala，我的号码是 0912 123 4567

Agent： 调用 ok_login → Okala 会发送短信 → 你输入验证码（如果你的客户端显示了表单，就在表单中输入；否则在聊天中输入）→ 登录成功

• 仅在你提出请求时才会发送验证码；同一号码每 2 分钟最多发送一次。
• 如果你的客户端支持 MCP 表单（elicitation），验证码会直接发送到服务端，不会经过模型。
• 登录信息保存在你的设备上（~/.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 中；每个工具都是一个带类型标注的异步函数，并附有说明何时使用该工具的文档字符串。欢迎提交问题和 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.com 网站的接口，这些接口可能随时更改，恕不另行通知。请合理控制请求频率。

作者

由 Sepehr Radmard（سپهر رادمرد）构建并维护。可通过 LinkedIn 联系，或在 GitHub 上关注 @sepehr071，获取更多面向伊朗网站的 MCP 服务；所有服务均列于 iran-mcp。如果它为您节省了时间，在仓库中点个星标就能帮助其他人发现它。

许可证

MIT