The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Horoshop MCP listing page.
Українська · Русский · English
Хорошоп MCP (horoshop-mcp): безкоштовний MCP-сервер з відкритим кодом, який підключає ШІ-агентів Claude, Cursor, Codex, Hermes Agent та інших до інтернет-магазину на платформі Хорошоп. Сервер працює на вашому комп'ютері, обслуговує кілька магазинів одночасно і дає агенту 118 інструментів для каталогу, замовлень, SEO, редиректів, фідів маркетплейсів, дизайну та налаштувань магазину.
Неофіційний проєкт. Хорошоп MCP не є продуктом компанії Хорошоп, не пов'язаний з нею і нею не підтримується. Інструменти адмінки працюють через внутрішні недокументовані запити, які Хорошоп може змінити без попередження. Нові сценарії спершу перевіряйте на тестовому магазині і лише потім запускайте на робочому.
store, тож агенція може працювати з магазинами всіх клієнтів через одне підключення.dryRun:false; ризиковані масові операції вимагають явного підтвердження; кожен запис перевіряється повторним читанням результату.Сторінка проєкту: igorshutko.github.io/horoshop-mcp
Документація: інструкція з встановлення для 22 клієнтів · довідник інструментів з усіма параметрами (англійською) · внутрішній устрій та особливості платформи (англійською).
1. Що потрібно. Node.js 18 або новіший і Git.
2. Доступи. Створіть в адмінці магазину окремого адміністратора (у російському інтерфейсі розділ «Настройки → Админы», кнопка «Добавить») і збережіть його логін і пароль. Та сама пара працює і для API, і для інструментів адмінки. Детальніше: як отримати доступи Хорошопу.
3. stores.json. Збережіть файл у місці, куди не мають доступу сторонні:
4. Підключіть ШІ-клієнт. Клонувати репозиторій не потрібно.
Claude Desktop, найпростіший шлях: завантажте horoshop-mcp.mcpb зі сторінки релізу і відкрийте файл. Claude Desktop поставить сервер сам і спитає, де лежить ваш stores.json. Термінал не потрібен.
Решта клієнтів запускають сервер через npx.
Claude Code:
Codex:
Cursor (~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), Windsurf, LM Studio, Kiro і більшість інших клієнтів:
Щоб закріпити конкретну версію, додайте тег до адреси: 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. Спробуйте. Попросіть агента:
| Напрям | Інструментів | Приклади |
|---|---|---|
| Налаштування і діагностика | 2 | список підключених магазинів, перевірка авторизації в API |
| Каталог (публічний API) | 4 | експорт та імпорт товарів, прив'язка фото, список стікерів |
| Замовлення (публічний API) | 3 | замовлення з UTM і даними доставки, зміна статусу та оплати, список статусів |
| Категорії, покупці, комплекти | 5 | дерево категорій, експорт та імпорт покупців, комплекти «купують разом» |
| Оплата, доставка, валюти | 5 | способи оплати та доставки, курси валют |
| B2B і вебхуки | 4 | групи покупців, рівні цін, підписки на події |
| Вітрина | 6 | справжній кошик покупця, застосування купона, перевірка варіантів на оформленні замовлення |
| Адмінка: універсальний рушій | 6 | читання, збереження або видалення будь-якого запису будь-якого розділу адмінки |
| Адмінка: замовлення та аналітика | 8 | читання і редагування замовлень, скасування чи видалення, пошук за номером, друк ТТН, дашборд продажів |
| Адмінка: товари, ціни, фото | 9 | масова зміна цін з відкатом, групове редагування та об'єднання, складські залишки, імпорт прайсу постачальника, імпорт фото за назвою файлу |
| Адмінка: характеристики та довідники | 15 | схеми характеристик категорій, шаблони товарів, довідники значень та їх переклади |
| Адмінка: категорії, сторінки, блог, банери, фільтри | 12 | категорії та інфосторінки з SEO-текстами, статті блогу, банери, індексовані сторінки фільтрів |
| Адмінка: SEO, sitemap, редиректи | 11 | canonical і noindex для пагінації, robots.txt, sitemap, 301-редиректи з перевіркою циклів і дублів |
| Адмінка: фіди маркетплейсів | 6 | фіди Rozetka, Hotline, Google, Facebook і Kasta: увімкнення, зіставлення, генерація, перевірка |
| Адмінка: дизайн та мови | 8 | налаштування теми, власний CSS, мови, переклади інтерфейсу |
| Адмінка: налаштування, маркетинг, фіскальні чеки | 14 | контакти й інформація про магазин, способи оформлення, коди відстеження (GTM, Pixel, GA4), купони, чеки Checkbox |
Кожен інструмент, його рівень доступу та всі параметри: довідник інструментів (англійською). Агентам зручніший docs/tools.json: той самий перелік без тексту, по одному компактному запису на інструмент.
Щоб не доводилось формулювати задачу словами, сервер віддає сім готових сценаріїв. Клієнт показує їх власним списком: у Claude Desktop це меню «+» у полі вводу, у Claude Code команда /mcp. Ви обираєте сценарій, заповнюєте одне-два поля, і агент іде за описаним порядком дій.
| Сценарій | Що робить |
|---|---|
| Перевірка магазину | Доступи, sitemap, robots, фіди і продажі. Тільки читання. |
| SEO категорії | Title, description і h1 двома мовами: спершу план, запис після підтвердження. |
| Товари без фото | Ті, що в наявності, показує першими: вони втрачають продажі зараз. |
| Зведення замовлень | Сума, статуси, джерела за UTM, найчастіші товари. |
| Фіди маркетплейсів | Що увімкнено, чи живі адреси, де не зіставлені наявність, ціна і категорії. |
| 301 редиректи списком | Перевірка циклів і дублів, потім масове створення. |
| Зміна цін з відкатом | Межі, попередження про великі зміни, параметри для повернення цін. |
Сценарії описані в src/prompts.ts і навмисно називають агенту конкретні інструменти та порядок кроків: модель не вгадує, як влаштований Хорошоп, а йде перевіреним шляхом.
Сервер бере всі параметри зі змінних середовища.
| Змінна | За замовчуванням | Призначення |
|---|---|---|
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; більші імпорти діляться автоматично. |
Формат файлу з магазинами:
Ключ задає назву, яку потім передають як store. baseUrl може бути просто доменом, зі слешем у кінці або з /api. Якщо конфігурації немає, сервер усе одно запускається і показує інструменти, а виклики пояснюють, чого бракує. Файл з помилкою зупиняє сервер зі зрозумілим повідомленням.
dryRun і повертають план: що зміниться, з якого значення і на яке. Нічого не записується, доки ви не повторите виклик з dryRun:false.confirm. horoshop_admin_products_price_set не приймає нульову чи від'ємну ціну, для понад 50 товарів вимагає точну кількість товарів, для змін понад 50% окреме підтвердження, і повертає готові параметри для відкату.OK, нічого не зберігши.{DISCOUNT_PERCENT} чи {site}. Інструменти запису не замінять їх звичайним текстом без allowPlaceholderLoss:true.horoshop_admin_design_get не віддає розділ оплати і маскує значення, схожі на ключі; horoshop_list_stores ніколи не повертає доступи.Ці обмеження йдуть від платформи, а не від сервера, і виміряні на реальних магазинах:
/api/ можна створювати й оновлювати, але не видаляти; категорії там доступні лише для читання. Видалення і редагування категорій закривають інструменти адмінки.limit. Гортайте через offset і limit (100 на сторінку працює добре).horoshop_orders_get.horoshop_admin_css_get повертає available:false замість порожнього результату.Повний список з подробицями: docs/INTERNALS.md (англійською).
stores*.json, резервні копії та файли .env додані до gitignore.Сервер поєднує три канали до магазину:
/api/<function>/): авторизація токеном, який кешується для кожного магазину й оновлюється непомітно. Використовується для каталогу, замовлень, покупців, довідкових даних, B2B і вебхуків./core-api/admin/security/login, далі класичні екрани адмінки. Адмінка влаштована одноманітно і розрізняє розділи за параметром handler (тип сутності): списки, форми редагування, збереження. Реєстр цих типів дає невеликому універсальному ядру доступ майже до кожного розділу, а для частих задач є окремі інструменти. Запис читає всю форму, змінює лише потрібні поля і відправляє решту без змін, тож поля, яких ви не торкалися, зберігаються./_widget/ajax_cart/) для питань, на які API не відповідає. Наприклад, чи зможе покупець дійти до оформлення замовлення з певним способом доставки.Архітектура, структура проєкту та особливості платформи: docs/INTERNALS.md (англійською).
Хорошоп MCP реалізує протокол Model Context Protocol для інтернет-магазинів на Хорошопі. Підключений до нього ШІ-агент читає та змінює магазин через 118 інструментів: товари, замовлення, покупців, категорії, SEO-тексти, 301-редиректи, фіди маркетплейсів, дизайн і налаштування. Сервер з відкритим кодом працює локально й може обслуговувати кілька магазинів одночасно.
Ні. Хорошоп MCP розробляється незалежно і не пов'язаний з компанією Хорошоп. Сервер використовує публічний API Хорошопу, а все, чого в API немає, робить тими самими запитами, які надсилає інтерфейс адмінки. Ці внутрішні запити можуть змінитися будь-коли, тому нові сценарії перевіряйте на окремому тестовому магазині.
Будь-який MCP-клієнт, який уміє запускати локальний stdio-сервер. В інструкції з встановлення є покрокове налаштування для 22 клієнтів, серед них Claude Code, Claude Desktop, Cursor, OpenAI Codex, Hermes Agent, VS Code з GitHub Copilot, Windsurf, Gemini CLI, Zed і Cline.
Node.js 18 або новіший, Git, а також логін і пароль адміністратора вашого магазину на Хорошопі. Запишіть доступи в stores.json, додайте сервер у ШІ-клієнт однією командою і зачекайте близько 20 секунд, поки перший запуск збере пакет.
Сервер спроєктований саме для цього. 57 з 71 інструмента запису лише показують план, доки ви не передасте dryRun:false, незворотні дії вимагають явного confirm, а кожен запис перевіряється читанням результату. Доступи зберігаються в локальному файлі, телеметрії немає. Дайте серверу окремого адміністратора з найвужчою роллю, якої достатньо.
Так. Опишіть усі магазини в одному файлі stores.json, а кожен виклик обирає магазин аргументом store. Так агенція працює з магазинами всіх клієнтів через одне підключення.
Хорошоп MCP безкоштовний і поширюється за ліцензією MIT. Платите лише за свій тариф Хорошопу і за ШІ-клієнт, яким користуєтеся.
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 - те саме для ШІ-агентів, які правлять цей код, CHANGELOG.md - що змінилось між версіями. Не публікуйте реальні дані магазинів в issues, логах і тестових файлах.
Хорошоп MCP створює та підтримує Ігор Шутко, агенція Target+.
Помилки та побажання: GitHub Issues.
MIT.