moysklad-mcp
MCP server for MoySklad — warehouse, inventory, orders, reports (Russia)
Open source Open in the app JSON README (API)
About
MCP server for MoySklad — warehouse, inventory, orders, reports (Russia)
Details
- Kind
- MCP servers
- Topic
- E-commerce & business
- Publisher
- theyahia
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.0.1
- Stars
- 5
- Forks
- 3
- Last push
- 2026-09-03T04:59:09Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:31
- Updated
- 2026-08-29 04:01:31
- Origin id
io.github.theYahia/moysklad-mcp
README
# MCP-сервер для МойСклад — 60 инструментов для ИИ-агента: товары, склад, заказы, финансы
Если вы искали, как подключить МойСклад к Claude или другому ИИ-агенту, — этот сервер закрывает весь торгово-складской цикл через JSON API 1.2: каталог и цены, остатки по складам, контрагенты, заказы покупателей и поставщикам, отгрузки, приёмки, перемещения, инвентаризации, списания, возвраты, счета, платежи и касса, отчёты по прибыли и оборотам, аудит и вебхуки. Спрашиваете «сколько футболок свободно к продаже» или «какая маржа по каждому товару за август» — получаете таблицу с цифрами, а не выгрузку в Excel. Цены во всех инструментах в рублях (перевод в копейки, которых требует API МойСклад, сервер делает сам), лимит запросов соблюдается автоматически.
[](https://www.npmjs.com/package/@theyahia/moysklad-mcp)
[](./LICENSE)
Часть **[WWmcp](https://github.com/theYahia/WWmcp)** — набора MCP-серверов для развивающихся рынков.
## Быстрый старт
### Claude Desktop
Добавьте в `claude_desktop_config.json`:
```json
{
"mcpServers": {
"moysklad": {
"command": "npx",
"args": ["-y", "@theyahia/moysklad-mcp"],
"env": {
"MOYSKLAD_TOKEN": "your-bearer-token"
}
}
}
}
```
Чтобы использовать логин и пароль вместо токена, замените блок `env` на:
```json
"env": { "MOYSKLAD_LOGIN": "you@example.com", "MOYSKLAD_PASSWORD": "your-password" }
```
### Claude Code
```bash
claude mcp add moysklad --env MOYSKLAD_TOKEN=your-bearer-token -- npx -y @theyahia/moysklad-mcp
```
### Cursor / Windsurf
Добавьте в настройки MCP:
```json
{
"moysklad": {
"command": "npx",
"args": ["-y", "@theyahia/moysklad-mcp"],
"env": { "MOYSKLAD_TOKEN": "your-bearer-token" }
}
}
```
## Авторизация
| Переменная | Описание |
| -------------------------------------- | --------------------------- |
| `MOYSKLAD_TOKEN` | Bearer-токен (предпочтительно) |
| `MOYSKLAD_LOGIN` + `MOYSKLAD_PASSWORD` | HTTP Basic-авторизация |
Токен выдаётся в МоёмСкладе: **Настройки → Пользователи → Токены доступа** (также работает `POST /security/token` с Basic-авторизацией). Генерация нового токена отзывает предыдущий.
**Нужные права:** у пользователя или токена должен быть доступ к тем сущностям, с которыми вы работаете. Читающим инструментам нужны права просмотра, создающим и изменяющим — права редактирования соответствующего типа документов. Вебхуки и часть отчётов требуют платного тарифа МойСклад.
## Цены
API МойСклад хранит деньги в **копейках** (1 рубль = 100 копеек). Сервер конвертирует автоматически:
- **На вход**: передавайте цены и суммы **в рублях** (например, `1500.50`)
- **На выход**: цены и суммы возвращаются **в рублях**
- (Отчёт `get_dashboard` проксируется как есть, поэтому денежные значения в нём остаются в копейках.)
Если у товара есть цена продажи, МойСклад требует **тип цены**. Сервер сам подставляет тип цены по умолчанию из вашего аккаунта (берёт из `list_price_types`); чтобы выбрать конкретный, передайте `price_type_href`.
## Инструменты (60)
### Товары и каталог
| Инструмент | Описание |
| -------------------------------------------------------- | ------------------------------------------------------------ |
| `search_products` | Поиск товаров по названию или артикулу |
| `get_product` | Товар по UUID (`raw` — полный объект) |
| `create_product` | Создать товар (тип цены подставляется автоматически) |
| `update_prices` | Обновить цены продажи, закупки и минимальную |
| `search_assortment` | Сквозной поиск по товарам, модификациям, услугам и комплектам |
| `list_price_types` | Типы цен (первый — по умолчанию) |
| `search_variants` / `search_bundles` / `search_services` | Поиск модификаций / комплектов / услуг |
| `create_service` | Создать услугу |
### Остатки
| Инструмент | Описание |
| -------------------- | ----------------------------------------------- |
| `get_stock` | Текущие остатки (количество, резерв, в пути) |
| `get_stock_by_store` | Остатки в разрезе складов |
| `get_stock_current` | Быстрый срез текущих остатков |
### Контрагенты
| Инструмент | Описание |
| --------------------- | ------------------------------------------- |
| `get_counterparties` | Поиск по названию, ИНН или телефону |
| `get_counterparty` | Полная карточка (`raw` — полный объект) |
| `create_counterparty` | Создать покупателя или поставщика |
### Заказы и отгрузки
| Инструмент | Описание |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `create_customer_order` / `get_orders` / `get_customer_order` / `update_customer_order_status` | Жизненный цикл заказа покупателя |
| `create_purchase_order` / `get_purchase_orders` | Заказы поставщикам |
| `create_demand` | Отгрузка, привязанная к заказу и складу |
| `create_supply` | Приёмка (поступление от поставщика) |
| `create_sales_return` / `create_purchase_return` | Возвраты от покупателей и поставщикам |
### Складские документы
| Инструмент | Описание |
| -------------------------------------- | ------------------------------- |
| `create_move` / `get_moves` | Перемещение между складами |
| `create_enter` / `get_enters` | Оприходование |
| `create_loss` / `get_losses` | Списание |
| `create_inventory` / `get_inventories` | Инвентаризация |
### Финансы
| Инструмент | Описание |
| --------------------------------------------------------------- | ------------------------------------ |
| `create_payment_in` / `create_payment_out` | Входящие и исходящие банковские платежи |
| `create_cash_in` / `create_cash_out` | Приходные и расходные кассовые ордера |
| `create_invoice_out` / `create_invoice_in` / `get_invoices_out` | Счета покупателям и от поставщиков |
### Отчёты
| Инструмент | Описание |
| ------------------- | ----------------------------------------------- |
| `get_profit_report` | Прибыль по товарам (выручка, себестоимость, маржа) |
| `get_sales_report` | Продажи по товарам (количество, выручка) |
| `get_dashboard` | Показатели дашборда за день, неделю, месяц |
| `get_turnover` | Оборачиваемость товаров за период |
| `get_money_report` | Текущие остатки денег по счетам и кассам |
### Справочники и аудит
| Инструмент | Описание |
| ------------------------------------------------------------- | --------------------------------------------------------------------- |
| `list_stores` / `list_organizations` | Склады и юрлица |
| `list_employees` / `list_currencies` / `list_product_folders` | Справочные данные |
| `get_metadata` | Метаданные сущностей (статусы, атрибуты) — здесь берутся href статусов заказа |
| `get_audit` / `get_entity_audit` | Журнал событий аккаунта и история одной сущности |
### Вебхуки и универсальные инструменты
| Инструмент | Описание |
| ------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `list_webhooks` / `create_webhook` / `update_webhook` / `delete_webhook` | Управление вебхуками (CREATE/UPDATE/DELETE/PROCESSED) |
| `get_documents` / `get_document` | Универсальные список и получение для любого типа сущностей, не покрытого выше |
## HTTP-транспорт
```bash
HTTP_PORT=3000 npx @theyahia/moysklad-mcp
# или
npx @theyahia/moysklad-mcp --http 3000
```
Эндпоинты: `POST /mcp` (JSON-RPC), `GET /health` (статус). CORS **выключен по умолчанию** — HTTP-эндпоинт действует от имени вашего токена МойСклад, поэтому задавайте `MOYSKLAD_HTTP_CORS_ORIGIN` только если доверенному браузерному origin это действительно нужно.
## Конфигурация (переменные окружения)
| Переменная | По умолчанию | Описание |
| -------------------------------------- | ------- | ---------------------------------------------------- |
| `MOYSKLAD_TOKEN` | — | Bearer-токен |
| `MOYSKLAD_LOGIN` / `MOYSKLAD_PASSWORD` | — | Basic-авторизация |
| `MOYSKLAD_RATE_BUCKET` | `20` | Сколько запросов разрешено в трёхсекундном окне |
| `MOYSKLAD_MAX_CONCURRENT` | `5` | Максимум параллельных запросов (МойСклад допускает 5 на пользователя) |
| `MOYSKLAD_HTTP_CORS_ORIGIN` | — | Разрешённый CORS-origin для HTTP-транспорта |
| `HTTP_PORT` | — | Запустить транспорт Streamable HTTP на этом порту |
## Ограничение частоты запросов
МойСклад считает «вес за 3 секунды» (≈45 единиц для токена решения, меньше для логина с паролем; отчёты `get_stock` и `get_stock_by_store` стоят по 5 единиц каждый). Встроенный лимитер — token bucket, который списывается по весу запроса, и по умолчанию он **консервативен** (`MOYSKLAD_RATE_BUCKET=20`), потому что API может временно отключить доступ после серии `429`. Повторы на `429`/`5xx` идут с задержкой и учитывают заголовок `X-Lognex-Retry-After`. С токеном решения корзину можно поднять ближе к 45.
## Решение проблем
| Симптом | Причина и что делать |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Auth not configured` | Задайте `MOYSKLAD_TOKEN` (или `MOYSKLAD_LOGIN` + `MOYSKLAD_PASSWORD`). |
| `auth error 401/403` | Токен недействителен или истёк, либо у пользователя нет прав на сущность. Новый токен отзывает старые. |
| `MoySklad HTTP 412 …` | Не хватает обязательного поля (например, исходящему платежу может требоваться статья расходов — передайте `expense_item_href`). Параметр указан в тексте ошибки. |
| Много `429` / медленно | Снизьте объём запросов или положитесь на встроенный лимитер; поднимайте `MOYSKLAD_RATE_BUCKET` только с токеном решения. |
| `HTTP 415` | Среда выполнения не отправляет gzip — используйте Node ≥18 (его `fetch` делает gzip автоматически). |
| Вебхуки и часть отчётов не работают | Требуют платного тарифа МойСклад. |
## E-commerce-стек
| Сервис | MCP-сервер | Что делает |
| -------- | ------------------------ | --------------------------- |
| МойСклад | `@theyahia/moysklad-mcp` | Склад, товары, заказы |
| СДЭК | `@theyahia/cdek-mcp` | Доставка, трекинг |
| DaData | `@theyahia/dadata-mcp` | Проверка адресов |
| ЮKassa | `@theyahia/yookassa-mcp` | Платежи |
## Демо-промпты
> «Покажи все товары с низким остатком (меньше 10 штук) и их текущие цены»
> «Создай заказ покупателя для контрагента „ООО Рога и Копыта“ на 50 штук „Widget Pro“ по 1500 рублей, потом сделай отгрузку с основного склада»
> «Перемести 20 штук SKU LP15 с основного склада в магазин, затем подними отчёт по прибыли за этот месяц»
## Разработка
```bash
npm install # зависимости + git-хуки (husky)
npm run build # tsc -> dist/
npm run lint # eslint
npm run typecheck # tsc --noEmit
npm test # vitest (требуется Node >=20)
npm run coverage # vitest с покрытием
```
Опубликованный рантайм поддерживает **Node ≥18**; тестовая оснастка требует **Node ≥20**.
## Справочник API
Основан на [JSON API 1.2 МойСклад](https://dev.moysklad.ru/doc/api/remap/1.2/).
## Лицензия
MIT
---
Часть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)