Хорошоп 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 і навмисно називають агенту конкретні інструменти та порядок кроків: модель не вгадує, як влаштований Хорошоп, а йде перевіреним шляхом.

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

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