Horoshop MCP

Хорошоп MCP: неофіційний MCP-сервер для магазинів на Хорошопі

Українська · Русский · English

Хорошоп MCP (horoshop-mcp): безкоштовний MCP-сервер з відкритим кодом, який підключає ШІ-агентів Claude, Cursor, Codex, Hermes Agent та інших до інтернет-магазину на платформі Хорошоп. Сервер працює на вашому комп'ютері, обслуговує кілька магазинів одночасно і дає агенту 118 інструментів для каталогу, замовлень, SEO, редиректів, фідів маркетплейсів, дизайну та налаштувань магазину.

Неофіційний проєкт. Хорошоп MCP не є продуктом компанії Хорошоп, не пов'язаний з нею і нею не підтримується. Інструменти адмінки працюють через внутрішні недокументовані запити, які Хорошоп може змінити без попередження. Нові сценарії спершу перевіряйте на тестовому магазині і лише потім запускайте на робочому.

• 118 інструментів на трьох рівнях: публічний API Хорошопу, адмінка та кошик вітрини.
• Багато магазинів, один сервер. Кожен інструмент приймає аргумент store, тож агенція може працювати з магазинами всіх клієнтів через одне підключення.
• Безпечно за замовчуванням. 57 з 71 інструмента запису лише показують план змін, доки ви не передасте 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. Підключіть ШІ-клієнт. Клонувати репозиторій не потрібно.

*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. Спробуйте. Попросіть агента:

• *«Покажи мої магазини на Хорошопі та перевір, чи працює авторизація.»*
• *«Покажи 10 найновіших замовлень у myshop зі статусом і сумою.»*
• *«Яких товарів у myshop немає в наявності? Покажи артикул, назву і ціну.»*
• *«Задай SEO-заголовок і опис категорії /shoes/ українською та російською. Лише план змін.»*
• *«Створи 301-редиректи з цього списку старих URL. Спершу покажи план змін.»*

Можливості

Кожен інструмент, його рівень доступу та всі параметри: довідник інструментів (англійською). Агентам зручніший docs/tools.json: той самий перелік без тексту, по одному компактному запису на інструмент.

Готові сценарії

Щоб не доводилось формулювати задачу словами, сервер віддає сім готових сценаріїв. Клієнт показує їх власним списком: у Claude Desktop це меню «+» у полі вводу, у Claude Code команда /mcp. Ви обираєте сценарій, заповнюєте одне-два поля, і агент іде за описаним порядком дій.

Сценарії описані в src/prompts.ts і навмисно називають агенту конкретні інструменти та порядок кроків: модель не вгадує, як влаштований Хорошоп, а йде перевіреним шляхом.

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

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

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

{

"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 ніколи не повертає доступи.
• Анотації інструментів. Кожен інструмент п