horoshop

horoshop-mcp

English: 一个适用于 Horoshop 电商平台的 MCP 服务。它让 Claude、Cursor 和任何其他 MCP 客户端都能直接访问 Horoshop 商店的 API，包括订单、商品目录、分类、客户、商品套装、参考数据和 Webhook。使用 npx -y horoshop-mcp 安装，并通过商店域名和管理员登录信息进行配置。llms-install.md 可让 AI Agent 为你完成整个设置流程。采用 MIT 许可。 以下文档为乌克兰语。

---

面向店主的说明，不涉及技术细节 — ecomkit.com.ua/instrumenty。

这是什么

这是一个适用于 Horoshop 的 MCP 服务。它让 Claude（或任何其他 MCP 客户端）都能直接访问你商店的 API：订单、商品目录、分类、客户、商品套装、配送和付款参考数据、Webhook。

接下来，你可以直接用日常语言提出要求：

• “显示上周仍在处理中的订单”
• “导出‘配件’分类下未填写 SEO 描述的商品”
• “更新这 20 个商品编号的价格”
• “8 月有多少客户注册”

该服务不会在 Horoshop 之上添加自己的逻辑，只是 官方 API 的轻量封装。

需要准备

• Node.js 20 或更高版本
• Horoshop 商店
• 管理员登录名和密码

通过 AI 安装

最快的方法是直接让助手帮你完成。将此提示词复制到 Claude Code、Claude Desktop 或 Cursor 中：

Встанови мені MCP-сервер horoshop-mcp.
Інструкція для тебе:
https://github.com/ecomkit-com-ua/horoshop-mcp/blob/main/llms-install.md
Прочитай її й виконай: спитай у мене домен магазину, логін і пароль адміна, пропиши конфіг
для того клієнта, у якому ти зараз працюєш, залиш на перший раз режим лише-читання
і перевір, що сервер відповідає.

助手会询问访问凭据，将配置块写入相应的配置文件，并检查连接。密码只会写入配置文件，不会出现在聊天或 git 中。

如果你觉得方便，也可以按照以下步骤手动操作。

第 1 步：为 API 创建单独的管理员账号

在商店管理面板中：设置 → 管理员 → 添加管理员。

请专门为 API 创建一个单独的账号，不要使用自己的个人账号。这样，只需一步即可撤销访问权限，而不会妨碍你登录；同时，日志也会显示集成访问具体执行了哪些操作。

Horoshop 不提供 API 密钥：需要使用管理员的普通登录名和密码进行身份验证。

第 2 步：连接服务

Claude Code — 在项目根目录的 .mcp.json 中：

{
  "mcpServers": {
    "horoshop": {
      "command": "npx",
      "args": ["-y", "horoshop-mcp"],
      "env": {
        "HOROSHOP_DOMAIN": "myshop.com.ua",
        "HOROSHOP_LOGIN": "api",
        "HOROSHOP_PASSWORD": "..."
      }
    }
  }
}

Claude Desktop — 配置方法相同，但文件为 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）。

Cursor — 在 ~/.cursor/mcp.json 中使用相同的配置块。

Cline — 在 cline_mcp_settings.json 中使用相同的配置块。

Gemini CLI — 在 ~/.gemini/settings.json 中使用相同的配置块。

VS Code（GitHub Copilot） — 同样在 .vscode/mcp.json 中配置，但服务需放在 servers 键下，而不是 mcpServers。

任何其他支持通过 stdio 使用 MCP 的客户端也可以，配置内容都相同。

完成后，重启客户端。

npx 会自动从 npm 下载软件包，无需另外安装。要使用尚未发布的最新代码，可直接从 GitHub 安装：["-y", "github:ecomkit-com-ua/horoshop-mcp"]。

配置文件中包含明文管理员密码。请勿将其提交到 git — 将 .mcp.json 添加到 .gitignore 中。

工具

读取：

• horoshop_orders_list — 订单信息，包括商品、配送、付款、折扣和 UTM 标记。 可按日期、编号和状态筛选
• horoshop_order_statuses — 商店的所有订单状态（需要 Horoshop 4.0+）
• horoshop_products_export — 商品目录中的商品：价格、库存情况、分类、属性、 库存数量、SEO。可按分类、商品编号和可见性筛选
• horoshop_categories_export — 带标识符的商品目录分类树
• horoshop_users_export — 已注册买家
• horoshop_store_reference — 一个工具即可获取商店参考数据：配送选项和类型、 付款选项和方式、含汇率的货币、商品图标；对于 B2B，还包括买家分组和 价格等级

写入：

• horoshop_products_import — 创建和更新商品
• horoshop_orders_update — 状态、付款标记、跟踪编号
• horoshop_users_import — 创建和更新买家
• horoshop_product_sets_import / horoshop_product_sets_remove — “组合购买更优惠”套装
• horoshop_webhook_subscribe / horoshop_webhook_unsubscribe — 订阅商店事件

通用调用：

• horoshop_call — 根据文档中的名称调用任意 API 函数。用于尚未提供独立工具的功能

商品导入请谨慎

horoshop_products_import 会直接写入线上商店，无法撤销。最危险的默认值如下：

• images、gallery_common 和 gallery_360 默认设置为 override: true — 这会在上传新照片前 删除当前图库。要添加照片而不删除现有照片，请传入 override: false；若要保持图库不变， 则完全不要传入这些字段
• accessories 和 gifts 会替换当前列表，而不是追加内容

批量导入前，请先用一个测试商品编号验证全部内容，并通过 horoshop_products_export 核对结果。

如果只需要只读访问权限，请设置 HOROSHOP_READONLY=1，这样写入工具就不会出现在列表中。

环境变量

必需：

• HOROSHOP_DOMAIN — 商店域名，例如 myshop.com.ua。可以带 https://，也可以不带
• HOROSHOP_LOGIN — 管理员登录名
• HOROSHOP_PASSWORD — 管理员密码

可选：

• HOROSHOP_READONLY=1 — 隐藏所有写入工具
• HOROSHOP_TIMEOUT_MS — 请求超时时间，默认值为 60000
• HOROSHOP_MAX_RESPONSE_BYTES — 响应大小上限，默认值为 100000。大型导出会被截断，并注明已显示的记录数 — 参见“翻页浏览大型导出”
• HOROSHOP_INSECURE_HTTP=1 — 使用 http 而非 https 访问（适用于测试商店）

翻页浏览大型导出

horoshop_orders_list、horoshop_products_export 和 horoshop_users_export 支持传入 limit 和 offset。但响应大小还会受到另一项独立限制 — HOROSHOP_MAX_RESPONSE_BYTES。

这两项限制彼此独立，这一点很重要。Horoshop 可能返回请求的 50 件商品，但响应预算只容得下 例如 17 件。其余 33 件已经返回，但不会显示。

因此，下一页的提示是根据**已显示的记录数，而不是 limit**计算的：如果页面被截断，服务端会提示从 offset 17 继续，而不是从 offset 50 继续。如果提示的是 offset 50，那 33 件商品就会永远丢失 — 后续请求都不会获取它们。

需要了解以下几点：

• 被截断的页面始终是有效的 JSON — 记录会从数组末尾整条移除，服务端不会在记录中间截断响应
• 如果响应预算连一条记录都容不下，服务端会明确提示：此时翻页无济于事，需要请求更少的字段 （include_params）或提高 HOROSHOP_MAX_RESPONSE_BYTES
• 如果 Horoshop 返回的记录数少于请求数，服务端会将其标记为最后一页，不再提供下一个 offset

值得了解的 Horoshop 限制

• 授权令牌有效期为 600 秒——服务会自动刷新
• catalog/export 每次最多返回 500 个商品；请通过 offset 翻页
• orders/get 和 users/export 在没有 limit 时会忽略 offset——服务始终会同时发送两者
• 同一事件最多只能设置 5 个 Webhook，而且 API 无法显示现有订阅
• 部分功能需要 Horoshop 4.0+ 或 B2B 模块；否则响应中会出现 UNDEFINED_FUNCTION

开发

npm install
npm run build
node dist/index.js

测试

npm test

npm test 会先运行 npm run build，因此测试始终针对编译后的 dist/ 运行，而不是针对源文件。无需真实商店：Horoshop 模拟服务会在随机端口 127.0.0.1 启动，因此测试不会发出任何外部请求。

文件分布如下：

• test/format.test.mjs — 响应格式化器的单元测试：大型 payload 截断、下一页提示、EMPTY 和 WARNING 状态、错误转换
• test/server.test.mjs — 集成测试。它们会在独立进程中启动真正的 dist/index.js，并通过 stdio 使用 JSON-RPC 与其通信，就像 MCP 客户端一样：握手、工具列表、只读模式、令牌生命周期、Horoshop 响应格式
• test/support/mock-horoshop.mjs — API 模拟服务：授权、过期令牌、响应封装、未经转换的 hooks/*、以 HTML 代替 JSON
• test/support/mcp-client.mjs — 用于测试的最小 MCP 客户端

单独运行一个文件：

node --test test/format.test.mjs

只需将新的测试文件命名为 test/<某个名称>.test.mjs，npm test 就会自动发现它。 test/support/ 中的文件不算测试，它们是辅助代码。

许可证

MIT。

隐私政策

不收集任何数据。 此服务不包含遥测、分析或使用情况报告功能， 也不会向 ecomkit 运营的任何服务发出请求。

• 凭据 — 您的商店域名、管理员登录名和密码保存在您自己的设备上、您自己的 MCP 客户端配置文件中，并且只会传输到您自己的商店。 作者无法访问这些信息。
• 您的数据会被发送到哪里 — 服务会将您商店的数据传入您与 AI 助手的对话， 因此这些数据会根据相应 AI 服务提供商的隐私政策（而非本政策）传送给您的 AI 服务提供商（Anthropic、Google、OpenAI 或 其他提供商）。请勿请求导出不得离开贵公司的数据。
• 第三方 — 除上述两方外，没有其他第三方。不会共享、出售或转移任何信息。
• 数据保留 — 作者不会保留任何数据，因为没有收到任何数据。
• 联系方式 — [email protected]

完整政策（乌克兰语和英语）： ecomkit.com.ua/pryvatnist-instrumenty

---

由 Сергій Троїцький 制作——互联网商店的启动、SEO 和自动化。 需要对 Horoshop 商店进行审计？ ecomkit.com.ua