MasterKala

masterkala-mcp：面向 AI Agent 的 MasterKala MCP 服务

让你的 AI Agent 在 MasterKala（مسترکالا）上选购电子产品。
这是一个面向 MasterKala 的非官方只读 MCP 服务。MasterKala 是一家伊朗电子产品和手机配件商店：搜索耳机、充电器、
充电宝和智能手表，比较实际价格和规格、阅读评价、查看库存和配送日期，并了解当日折扣，所有操作都可通过 Claude、Cursor 或 Copilot 完成。

面向 AI Agent · 原因 · 功能 · 快速开始 · 工具 · 工作原理 · 须知 · 常见问题 · 配置 · فارسی · 开发 · 相关服务

面向 AI Agent

• **简介：**面向 MasterKala（masterkala.com，伊朗）的非官方 MCP 服务（模型上下文协议）。MasterKala 是一家销售自有库存商品的电子产品和手机配件商店。支持波斯语或英语查询；价格以托曼计。
• 安装：uvx masterkala-mcp 或 claude mcp add masterkala -- uvx masterkala-mcp。传输方式：stdio。需要 uv（Python 3.10+）。
• **身份验证：**无需验证，不需要 API 密钥或账户。可选的 MASTERKALA_MCP_PROXY（用于向 masterkala.com 发送请求的 HTTP 代理 URL，或以逗号分隔的代理列表）；系统代理设置不会生效。
• **访问权限：**只读。无法登录、使用购物车、下单或发布评价，因此调用任何工具前都无需确认。
• **工具：**共 14 个，名称均以 mk_ 为前缀。可从 mk_find_cheapest、mk_search、mk_deals、mk_browse 开始。 典型调用顺序：mk_find_cheapest -> mk_product -> mk_shipping。
• **适用场景：**用户想找最便宜的可下单商品、比较规格或价格、查看评价和库存、估算配送时间、了解当前折扣，或获取 MasterKala 购物指南时。
• **不适用场景：**用户想要购买商品（Agent 找到商品后，用户需在 masterkala.com 上下单）、需要查询其他商店，或需要送货到特定地址时：配送时间只是针对德黑兰和“其他城市邮寄”的估算，依据的是默认的德黑兰地址。
• 输出：精简的 JSON。价格以托曼计（final_price 即实际支付金额），评分为 1–5 分（null 表示暂无评价）。数字型商品 ID 可在工具间传递。
• 机器可读信息：server.json 和 iran-mcp 目录（TOOLS.md、servers.json、llms.txt）。

为什么

MasterKala 列出了数千种配件，搜索“power bank”会同时显示真正的充电宝、硅胶保护套、缺货商品，以及仅在门店销售的商品。要找到实际可以下单的最便宜商品，以及送货上门的价格，就得一页页翻看搜索结果并打开商品页面。使用 masterkala-mcp 的 Agent 几秒钟就能完成：

你： 现在可以下单、送到德黑兰的最便宜的小米充电宝？

Agent： 调用 mk_find_cheapest(query="پاوربانک شیائومی") → mk_shipping(product_id=26935)

总价	商品	价格	运费
4,338,000	پاوربانک 10000 شیائومی گلوریمی Glorimi LightCore 22.5W	4,188,000（优惠 5%）	150,000，周六 15:00-18:00
5,291,000	پاوربانک فوق نازک مگنتی 5000 Glorimi FitCore Mag 20W	5,291,000（优惠 4%）	免费（订单满 5M）
5,401,000	پاوربانک 20000 شیائومی گلوریمی Glorimi LightCore 22.5W	5,401,000（优惠 6%）	免费（订单满 5M）

即使加上 150,000 的快递费，10,000 mAh 的 LightCore 仍然最便宜。20,000 mAh 的 LightCore 包邮，容量翻倍，价格多 1,063,000。要我用 mk_specs 比较它们的规格吗？

_{工具输出摘录自 2026-10-03；价格随时可能变化。价格单位为托曼。}

功能

• 搜索：按波斯语或英语名称搜索商品，并查看价格、折扣和库存
• 查找最便宜商品：找到有库存的匹配商品，并过滤掉保护壳和保护套
• 浏览：按价格、库存或日期排序浏览任意类别、品牌或标签，并按价格范围、品牌和颜色筛选
• 查看：完整商品详情，包括颜色、库存数量、规格、并排比较和评论
• 查询配送：德黑兰下一班快递时段、寄往其他城市的邮寄服务、运费和当日截单时间
• 发现优惠：查看折扣页面上的优惠，以及 MasterKala 博客中的选购指南和读者提问
• 查找门店：查找 MasterKala 在德黑兰的实体分店地址、电话和地图位置
• 专为只读而设计：无需登录，不提供购物车、下单或发布评论功能

示例提示词：

• “找出 3 到 5 百万托曼之间最便宜的蓝牙耳机，并告诉我哪款评论最好？”
• “比较 Green Lion Ocean 和 Awei T66 的规格。”
• “蓝色的 CMF Buds Pro 2 有货吗？什么时候能送到德黑兰？”
• “今天智能手表有哪些最大折扣？”
• “MasterKala 在德黑兰有哪些实体门店？”
• بهترین تخفیف‌های امروز مسترکالا روی پاوربانک چیه؟
• ارزان‌ترین هندزفری بلوتوث موجود را پیدا کن و بگو کی به تهران می‌رسد.
• مشخصات دو ساعت هوشمند را کنار هم مقایسه کن و نظر خریداران را بگو.

快速开始

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

claude mcp add masterkala -- uvx masterkala-mcp

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

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

codex mcp add masterkala -- uvx masterkala-mcp

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

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

所有工具都以 mk_ 为前缀。商品 ID 是类似 24855 的数字；分类 ID 来自 mk_categories，品牌 slug 来自 mk_brands。

全部 14 个工具都标注了 readOnlyHint: true，并返回精简 JSON，不会让 Agent 的上下文被大量内容淹没。

工作原理

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  masterkala-mcp  (runs on your machine)
      │
      │  HTTPS
      └──────▶  masterkala.com   JSON API, listing fragments, product pages

masterkala-mcp 在本地运行，并调用 masterkala.com 网站使用的相同公开端点。 中间没有托管服务，不需要 API 密钥，也不会将你的任何信息发送到其他地方。 请求通过模拟 Chrome 的 HTTP 客户端发出，同时最多处理 2 个请求，并加入短暂的随机延迟；如果连接中断，最多重试两次。分类和品牌列表会缓存一小时。评价、评论和商品描述文本均视为不可信的网站内容，并会截短。

有用信息

• 价格单位为 Toman。 final_price 是实付价格，price 是折扣前价格，discount_pct 是整数百分比。网站的结构化数据以 Rial 为单位；服务端会进行换算。
• 大多数商品每笔订单满 5,000,000 Toman 即可免运费（大型音箱等大件商品始终不免运费；这类商品的 mk_shipping 会返回 free_shipping_from: null）；未满额时，2026-10-03 的德黑兰快递和邮政运费分别为 150,000 / 155,000 Toman。由于没有地址 API，mk_shipping 会估算德黑兰及“其他城市邮政”的运费。
• 库存： in_stock 表示目前可在线下单。其他状态包括：ناموجود（售罄）、به زودی（即将推出）、موجود در شعب حضوری（仅在实体门店有售）。
• 图片： 每件商品都有 image，即绝对 https URL（mk_search、mk_find_cheapest 和 mk_browse 返回 328 px 的 webp；mk_deals 返回 240 px 的图片；mk_specs 返回原始 jpg）。mk_product 会提供 600 px 的 image，以及一个 images 列表（最多 4 张）。结果中会省略值为 null 或空的字段；只有当 stock_status 不为“موجود”（有货）时才会显示；评价和评论文本会截断至 400 个字符（博客讨论串保留 3 条回复，more_replies 记录其余回复数）。
• 评分范围为 1–5， 尚无人评价的商品则为 null。
• 使用波斯语查询效果最佳（هندزفری、پاوربانک），但英文品牌和型号名称也可用（xiaomi、Buds Pro）。
• 关键词商品列表不支持排序。 搜索关键词时使用 mk_search 或 mk_find_cheapest；需要排序、价格范围或筛选条件时，请使用带分类 ID、品牌 slug 或标签 ID 的 mk_browse。
• 速率限制： 网站的 robots.txt 禁止爬虫访问其 API 路径，因此请保持较低的请求频率（约每秒一次）。服务端已限制并发，并会添加短暂延迟。
• 不支持的功能： 登录、购物车、订单、付款、愿望清单或发布评价；不支持其他商店，也不能配送到特定地址。
• 代理： 如需使用代理，请设置 MASTERKALA_MCP_PROXY（参见配置）。

常见问题

npx @modelcontextprotocol/inspector uvx masterkala-mcp

配置

波斯语：MasterKala MCP 服务

claude mcp add masterkala -- uvx masterkala-mcp

开发

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

工具位于 src/masterkala_mcp/catalog.py、product.py 和 blog.py 中；每个工具都是带类型标注的异步函数，并附有说明何时使用它的文档字符串。欢迎提交问题和 PR，尤其欢迎新增工具和修复网站变更导致的问题。

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

相关服务

• iran-mcp：伊朗各类服务 MCP 服务目录
• Digikala MCP server：服务于伊朗最大的在线商店
• Technolife MCP server：提供电子产品价格和分期价格
• Torob MCP server：比较伊朗各家商店的价格
• Okala MCP server：在线购买食品杂货
• Banimode MCP server：时尚商品

免责声明

本项目为非官方项目，与 MasterKala 无关联，也未获得其认可。本项目仅支持只读操作，并使用 masterkala.com 网站的公开接口，这些接口可能随时变更，恕不另行通知。请合理控制请求频率。

作者

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

许可证

MIT

如果这个项目帮你省下了几次点击，欢迎点个星标，让更多人发现它。