Horoshop MCP

Хорошоп MCP：面向 Хорошоп 商店的非官方 MCP 服务

乌克兰语 · 俄语 · 英语

Хорошоп MCP（horoshop-mcp）：免费的开源 MCP 服务，可将 Claude、Cursor、Codex、Hermes Agent 等 AI Agent 连接到 Хорошоп 平台上的网店。服务运行在您的计算机上，可同时管理多家商店，并为 Agent 提供 118 个工具，用于管理商品目录、订单、SEO、重定向、市场平台 Feed、设计和商店设置。

非官方项目。 Хорошоп MCP 不是 Хорошоп 公司的产品，与该公司无关，也不受其支持。管理后台工具通过 Хорошоп 可能随时更改且不另行通知的内部未公开请求运行。请先在测试商店中验证新操作，然后再在正式商店中执行。

• 118 个工具，涵盖三个层级：Хорошоп 公开 API、管理后台和店面购物车。
• 多家商店，一个服务。 每个工具都接受 store 参数，因此代理机构可以通过一个连接管理所有客户的商店。
• 默认安全。 71 个写入工具中有 57 个只会显示变更计划，除非您传入 dryRun:false；高风险批量操作需要明确确认；每次写入都会通过重新读取结果来验证。
• 本地运行。 服务通过 stdio 在您的计算机上运行。访问凭据保存在由您控制的文件中。

目录

• 快速开始
• 功能
• 现成的操作场景
• 设置
• 防止错误修改
• 平台限制
• 安全
• 工作原理
• 常见问题
• 开发
• 作者与联系方式
• 许可证

项目主页：igorshutko.github.io/horoshop-mcp

文档：22 个客户端的安装指南 · 包含所有参数的工具参考（英文） · 内部结构及平台特性（英文）。

快速入门

1. 所需条件。 Node.js 18 或更高版本，以及 Git。

2. 访问凭据。 在商店管理后台创建一个单独的管理员（俄语界面中的「Настройки → Админы」部分，点击「Добавить」按钮），并保存其登录名和密码。同一组凭据可用于 API 和管理后台工具。详情请见：如何获取 Хорошоп 的访问凭据。

3. stores.json。 将文件保存在他人无法访问的位置：

{
  "myshop": { "baseUrl": "https://myshop.com.ua", "login": "api-user", "password": "REPLACE_ME" }
}

4. 连接 AI 客户端。 无需克隆代码库。

Claude Desktop，最简单的方式： 从发布页面下载 horoshop-mcp.mcpb 并打开文件。Claude Desktop 会自动安装服务，并询问您的 stores.json 所在位置。无需使用终端。

其他客户端通过 npx 启动服务。

Claude Code：

claude mcp add horoshop -s user -e HOROSHOP_STORES_FILE=/abs/path/to/stores.json -- npx -y github:IgorShutko/horoshop-mcp

Codex：

codex mcp add horoshop --env HOROSHOP_STORES_FILE=/abs/path/to/stores.json -- npx -y github:IgorShutko/horoshop-mcp

Cursor (~/.cursor/mcp.json)、Claude Desktop (claude_desktop_config.json)、Windsurf、LM Studio、Kiro 以及大多数其他客户端：

{
  "mcpServers": {
    "horoshop": {
      "command": "npx",
      "args": ["-y", "github:IgorShutko/horoshop-mcp"],
      "env": { "HOROSHOP_STORES_FILE": "/abs/path/to/stores.json" }
    }
  }
}

若要固定具体版本，请在地址末尾添加标签：github:IgorShutko/horoshop-mcp#v0.2.0。

在 Windows 上，请使用 "command": "cmd", "args": ["/c", "npx", "-y", "github:IgorShutko/horoshop-mcp"]。首次启动时会下载并构建软件包，大约需要 20 秒。VS Code、Zed、Hermes Agent、Gemini CLI、OpenCode、Goose 及其他客户端有各自的配置格式：请参阅安装指南，其中也介绍了通过克隆进行安装以及客户端超时设置。

5. 试试看。 请 Agent：

• 「显示我在 Хорошоп 上的商店，并检查授权是否有效。」
• 「显示 myshop 中最新的 10 个订单，以及状态和金额。」
• 「myshop 中有哪些商品缺货？显示货号、名称和价格。」
• 「为 /shoes/ 分类设置乌克兰语和俄语的 SEO 标题与描述。只提供变更计划。」
• 「根据这份旧 URL 列表创建 301 重定向。先显示变更计划。」

功能

方向	工具数	示例
配置与诊断	2	已连接商店列表、检查 API 授权
商品目录（公共 API）	4	导出和导入商品、关联照片、贴纸列表
订单（公共 API）	3	带有 UTM 和配送信息的订单、更改状态和付款、状态列表
类别、买家、套装	5	类别树、导出和导入买家、「一起购买」套装
付款、配送、货币	5	付款和配送方式、汇率
B2B 和 Webhook	4	买家群组、价格级别、事件订阅
商店前台	6	买家的真实购物车、使用优惠券、检查结账时的商品变体
管理后台：通用引擎	6	读取、保存或删除管理后台任意分区中的任意记录
管理后台：订单与分析	8	读取和编辑订单、取消或删除订单、按编号搜索、打印 TTN、销售仪表板
管理后台：商品、价格、照片	9	批量更改价格并可撤销、批量编辑和合并、库存余量、导入供应商价目表、按文件名导入照片
管理后台：属性与参考数据	15	类别属性方案、商品模板、数值参考数据及其翻译
管理后台：类别、页面、博客、横幅、筛选器	12	带 SEO 文本的类别和信息页面、博客文章、横幅、可编入索引的筛选页面
管理后台：SEO、sitemap、重定向	11	分页的 canonical 和 noindex、robots.txt、sitemap、检查循环和重复项的 301 重定向
管理后台：电商平台 Feed	6	Rozetka、Hotline、Google、Facebook 和 Kasta Feed：启用、映射、生成、检查
管理后台：设计与语言	8	主题设置、自定义 CSS、语言、界面翻译
管理后台：设置、营销、税务收据	14	商店联系方式和信息、结账方式、跟踪代码（GTM、Pixel、GA4）、优惠券、Checkbox 收据

每个工具、其访问级别和所有参数：工具手册（英文）。对于 Agent，使用 docs/tools.json 更方便：同一份列表，不含文本说明，每个工具对应一条简洁记录。

预设场景

为了省去用文字描述任务的麻烦，服务提供七个预设场景。客户端会以自己的列表展示这些场景：在 Claude Desktop 中，这是输入框里的「+」菜单；在 Claude Code 中，则是 /mcp 命令。选择一个场景，填写一两个字段，Agent 就会按照描述的操作顺序执行。

场景	功能
商店检查	访问权限、sitemap、robots、Feed 和销售情况。仅供读取。
类别 SEO	两种语言的 Title、description 和 h1：先制定计划，确认后再写入。
缺少照片的商品	有库存的商品优先显示：它们正在损失销售额。
订单汇总	金额、状态、UTM 来源、最常见的商品。
电商平台 Feed	已启用的项目、地址是否有效、库存、价格和类别映射缺失的位置。
批量创建 301 重定向	检查循环和重复项，然后批量创建。
可撤销的价格更改	范围、大幅变更警告、用于恢复价格的参数。

场景定义在 src/prompts.ts 中，并有意为 Agent 指定具体工具和操作步骤：模型无需猜测 Хорошоп 的运作方式，而是沿着经过验证的路径执行。

Налаштування

Сервер бере всі параметри зі змінних середовища.

Змінна	За замовчуванням	Призначення
HOROSHOP_STORES_FILE	немає	Шлях до JSON-файлу з магазинами (рекомендований спосіб).
HOROSHOP_STORES	немає	Той самий JSON прямо в змінній. Має пріоритет над файлом.
HOROSHOP_DEFAULT_STORE	єдиний магазин, якщо він один	Магазин для викликів без store.
HOROSHOP_TIMEOUT_MS	120000	Тайм-аут одного HTTP-запиту до магазину.
HOROSHOP_MAX_RESPONSE_BYTES	100000	Відповіді інструментів читання, більші за цей розмір, не повертаються: сервер натомість підказує, як звузити запит. Також приймається стара назва HOROSHOP_EXPORT_MAX_BYTES.
HOROSHOP_WIDGET_RETRY	увімкнено	off вимикає автоматичний повтор ідемпотентних записів через віджети адмінки (див. обмеження платформи).
HOROSHOP_GRID_REPAIR_MAX	розраховується для кожного списку, не більше 60	Скільки додаткових сторінок можна перечитати, якщо довгий список в адмінці зсувається під час читання.
HOROSHOP_IMPORT_POST_LIMIT	120000	Максимум байтів в одному запиті catalog/import; більші імпорти діляться автоматично.

Формат файлу з магазинами:

{
  "myshop": { "baseUrl": "https://myshop.com.ua", "login": "api-user", "password": "REPLACE_ME" },
  "othershop": { "baseUrl": "othershop.ua", "login": "api-user", "password": "REPLACE_ME" }
}

Ключ задає назву, яку потім передають як store. baseUrl може бути просто доменом, зі слешем у кінці або з /api. Якщо конфігурації немає, сервер усе одно запускається і показує інструменти, а виклики пояснюють, чого бракує. Файл з помилкою зупиняє сервер зі зрозумілим повідомленням.

Захист від помилкових змін

• Спершу план. 57 з 71 інструмента запису за замовчуванням працюють з dryRun і повертають план: що зміниться, з якого значення і на яке. Нічого не записується, доки ви не повторите виклик з dryRun:false.
• Підтвердження для незворотних і масових дій. Видалення або скасування замовлень, видалення довідників, зміна аліасу фіду (це публічна адреса фіду) та запуск імпорту прайсу вимагають явного confirm. horoshop_admin_products_price_set не приймає нульову чи від'ємну ціну, для понад 50 товарів вимагає точну кількість товарів, для змін понад 50% окреме підтвердження, і повертає готові параметри для відкату.
• Перевірка читанням. Інструменти запису перечитують результат, часто іншим каналом (наприклад, запис через адмінку перевіряється через публічний API), бо Хорошоп інколи відповідає OK, нічого не зберігши.
• Захист шаблонів. Тексти вітрини часто містять змінні на кшталт {DISCOUNT_PERCENT} чи {site}. Інструменти запису не замінять їх звичайним текстом без allowPlaceholderLoss:true.
• Обмеження розміру. Інструменти читання вимірюють відповідь і не повертають понад 100 KB, а підказують, як звузити запит. Один виклик не засмітить розмову.
• Секрети приховані. horoshop_admin_design_get не віддає розділ оплати і маскує значення, схожі на ключі; horoshop_list_stores ніколи не повертає доступи.
• Анотації інструментів. Кожен інструмент позначений як читання, запис або руйнівний запис, тож клієнти, які це підтримують, можуть автоматично дозволяти читання і питати дозволу перед записом.

Обмеження платформи

Ці обмеження йдуть від платформи, а не від сервера, і виміряні на реальних магазинах:

• У публічному API є імпорт, але немає видалення. Товари та покупців через /api/ можна створювати й оновлювати, але не видаляти; категорії там доступні лише для читання. Видалення і редагування категорій закривають інструменти адмінки.
• Експорт каталогу віддає не більше 500 товарів за виклик, незалежно від limit. Гортайте через offset і limit (100 на сторінку працює добре).
• Товари в замовленні змінити не можна ні через API, ні через адмінку. Одержувача, адресу, оплату й коментар менеджера змінити можна.
• Окреме фото з галереї видалити не можна. Хорошоп не має такого маршруту.
• Записи через віджети адмінки інколи губляться. Під час сплесків навантаження частина запитів потрапляє на вітрину замість адмінки, і нічого не зберігається. Ідемпотентні записи (оновлення, видалення) повторюються до п'яти разів, а пропуски потрапляють у звіт; створення не повторюється ніколи, щоб не з'явилися дублікати.
• Відкриття замовлення в адмінці піднімає його на верх списку замовлень (платформа оновлює дату рядка). Дані замовлення не змінюються; інструменти відкривають редактор якомога рідше.
• Дашборд аналітики показує фіксований період. Для довільних дат збирайте дані через horoshop_orders_get.
• Деякі розділи існують, лише якщо в магазині підключено модуль, наприклад редактор власного CSS. Тоді horoshop_admin_css_get повертає available:false замість порожнього результату.

Повний список з подробицями: docs/INTERNALS.md (англійською).

Безпека

• Тримайте доступи у файлі магазинів або в змінних середовища, ніколи не вставляйте їх у запити до агента чи в аргументи інструментів. stores*.json, резервні копії та файли .env додані до gitignore.
• Створіть для сервера окремого адміністратора з найвужчою роллю, якої достатньо для роботи. Щоб закрити доступ, видаліть цього користувача.
• Сервер звертається лише до налаштованих магазинів, до сервісу завантаження зображень Хорошопу, на який вказує адмінка під час імпорту фото, і до адрес зображень, які ви самі просите завантажити. Телеметрії немає.
• API-токени та сесії адмінки зберігаються лише в пам'яті.
• Повідомляючи про помилку, не вставляйте в issue реальні дані магазину, замовлень чи доступи.
• Модель безпеки, перелік того, що маскується у відповідях, і куди писати про вразливість: SECURITY.md.

Як це працює

Сервер поєднує три канали до магазину:

flowchart TD
  AI["ШІ-клієнт<br/>Claude · Cursor · Codex · Gemini CLI"] -->|"MCP, stdio"| S["horoshop-mcp<br/>118 інструментів"]
  S --> G{"Це запис?"}
  G -->|"читання"| CH["Три канали до магазину"]
  G -->|"запис: спершу план,<br/>виконання лише з dryRun:false"| CH
  CH --> P["Публічний API<br/>каталог, замовлення, покупці"]
  CH --> A["Адмінка<br/>SEO, фіди, дизайн, налаштування"]
  CH --> V["Вітрина<br/>кошик і оформлення"]
  P --> ST["Ваш магазин на Хорошопі<br/>аргумент store обирає, який саме"]
  A --> ST
  V --> ST

1. Публічний API (/api/<function>/): авторизація токеном, який кешується для кожного магазину й оновлюється непомітно. Використовується для каталогу, замовлень, покупців, довідкових даних, B2B і вебхуків.
2. Адмінка: сесія через /core-api/admin/security/login, далі класичні екрани адмінки. Адмінка влаштована одноманітно і розрізняє розділи за параметром handler (тип сутності): списки, форми редагування, збереження. Реєстр цих типів дає невеликому універсальному ядру доступ майже до кожного розділу, а для частих задач є окремі інструменти. Запис читає всю форму, змінює лише потрібні поля і відправляє решту без змін, тож поля, яких ви не торкалися, зберігаються.
3. Вітрина: власний віджет кошика магазину (/_widget/ajax_cart/) для питань, на які API не відповідає. Наприклад, чи зможе покупець дійти до оформлення замовлення з певним способом доставки.

Архітектура, структура проєкту та особливості платформи: docs/INTERNALS.md (англійською).

Часті запитання

Що таке Хорошоп MCP?

Хорошоп MCP реалізує протокол Model Context Protocol для інтернет-магазинів на Хорошопі. Підключений до нього ШІ-агент читає та змінює магазин через 118 інструментів: товари, замовлення, покупців, категорії, SEO-тексти, 301-редиректи, фіди маркетплейсів, дизайн і налаштування. Сервер з відкритим кодом працює локально й може обслуговувати кілька магазинів одночасно.

Хорошоп MCP 是 Хорошоп 的官方产品吗？

不是。Хорошоп MCP 由独立团队开发，与 Хорошоп 公司无关。服务使用 Хорошоп 的公开 API；对于 API 不支持的功能，则使用与后台管理界面相同的请求。这些内部请求随时可能发生变化，因此请在单独的测试商店中验证新场景。

哪些 AI 助手支持 Хорошоп MCP？

任何能够运行本地 stdio 服务的 MCP 客户端都可以使用。安装说明提供了 22 个客户端的分步配置指南，包括 Claude Code、Claude Desktop、Cursor、OpenAI Codex、Hermes Agent、搭配 GitHub Copilot 的 VS Code、Windsurf、Gemini CLI、Zed 和 Cline。

连接 Хорошоп 商店需要什么？

需要 Node.js 18 或更高版本、Git，以及 Хорошоп 商店管理员的登录名和密码。将凭据写入 stores.json，用一条命令将服务添加到 AI 客户端，然后等待约 20 秒，让首次启动完成构建。

允许 AI Agent 访问商店安全吗？

该服务正是为此设计的。71 个写入工具中，有 57 个只会显示操作计划，除非你传入 dryRun:false；不可逆操作需要明确提供 confirm，每次写入都会通过读取结果进行验证。凭据保存在本地文件中，不收集遥测数据。请为服务单独创建一个管理员账号，并赋予足以完成任务的最低权限角色。

可以通过一个服务管理多个商店吗？

可以。在同一个 stores.json 文件中列出所有商店，每次调用时通过 store 参数选择商店。这样，代理机构就能通过一个连接管理所有客户的商店。

Хорошоп MCP 的费用是多少？

Хорошоп MCP 免费提供，并采用 MIT 许可证。你只需支付自己的 Хорошоп 套餐费用，以及所使用的 AI 客户端费用。

开发

git clone https://github.com/IgorShutko/horoshop-mcp.git
cd horoshop-mcp
npm install          # installs dependencies and builds dist/
npm run watch        # recompile on change
npm run inspect      # build and open the MCP Inspector
npm run docs:tools   # regenerate docs/TOOLS.md from the running server

MCP 客户端只会启动一次服务，因此重新构建后，请重启客户端。如果磁盘上的构建版本比正在运行的进程更新，horoshop_check_auth 和 horoshop_list_stores 会返回 stale:true。

evaluation/horoshop_eval.xml 汇集了只读问题，用于检查模型能否通过服务处理实际任务。答案取决于连接的商店，因此请在自己的测试商店中填写答案。

npm test 会启动构建好的服务，并检查每个客户端所依赖的内容：118 个工具全部就绪、stdout 通道干净、每个工具都能路由到商店。CI 也会在 Node 18 和 22 上运行相同的命令。

欢迎提交 Issues 和 pull requests：CONTRIBUTING.md 介绍相关规范，AGENTS.md 是供修改此代码的 AI Agent 遵循的相同规范，CHANGELOG.md 记录了各版本之间的变更。请勿在 issues、日志和测试文件中公开真实商店数据。

作者与联系方式

Хорошоп MCP 由 Игорь Шутко 和 Target+ 代理机构创建并维护。

• Telegram： @shutko_igor
• Telegram 频道：@shutko_ads

问题与建议：GitHub Issues。

许可证

MIT。