moysklad-mcp-ru

# moysklad-mcp-ru: AI-доступ к МойСклад для Claude Code, Cursor, Codex и Cowork

> 🇬🇧 [English version](README.en.md)
>
> **Ведёте учёт в МойСклад — дайте ИИ прямой доступ к вашему аккаунту.** Один
> MCP-сервер над JSON API 1.2 МойСклад: остатки, товары, заказы, контрагенты,
> отчёты (прибыль, обороты, деньги) и **запись документов** (приёмки, отгрузки,
> заказы, счета, возвраты) — напрямую по API, без браузера. Числа приходят из
> **реального API**, а не выдумываются моделью. **Два гейта на запись** не дают
> случайно создать или провести документ в боевом учёте. Авто-пагинация,
> мультикабинет, поиск по-русски. Для Claude Code, Cursor, Codex, Cowork и Claude
> Desktop.

[![PyPI](https://img.shields.io/pypi/v/moysklad-mcp-ru?label=pypi&color=B5491F)](https://pypi.org/project/moysklad-mcp-ru/)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-2D7D4F)](https://registry.modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Тулов](https://img.shields.io/badge/%D1%82%D1%83%D0%BB%D0%BE%D0%B2-32-2D7D4F)](#что-внутри)
[![Тестов](https://img.shields.io/badge/%D1%82%D0%B5%D1%81%D1%82%D0%BE%D0%B2-104-2D7D4F)](https://github.com/ilyautov/moysklad-mcp-ru/actions/workflows/ci.yml)
[![Сайт](https://img.shields.io/badge/%D1%81%D0%B0%D0%B9%D1%82-aifrontier.tech-9A3E1A)](https://moysklad-mcp-ru.aifrontier.tech)
[![Звёзды](https://img.shields.io/github/stars/ilyautov/moysklad-mcp-ru?style=flat&label=%D0%B7%D0%B2%D1%91%D0%B7%D0%B4%D1%8B&color=B5491F&logo=github&logoColor=white)](https://github.com/ilyautov/moysklad-mcp-ru/stargazers)

<p align="center">
  <a href="https://moysklad-mcp-ru.aifrontier.tech">
    <img src="assets/social-preview.png" alt="moysklad-mcp-ru: МойСклад в ИИ-ассистенте. Остатки, заказы, отчёты и запись документов через JSON API 1.2, с гейтом безопасности" width="760">
  </a>
</p>

**Быстрый старт**, без установки в систему:

```bash
uvx moysklad-mcp-ru
```

Клиенты, токен и способ «попроси своего ИИ поставить»: в разделе [«Установка»](#установка).

> ⚠️ **alpha.** Помогает с операционкой учёта, но это инструмент, а не замена
> бухгалтера. Курированное ядро и срез записи выверены боем на тестовом кабинете;
> импортированные из доки методы — карта для разведки (пути надёжны, тела
> write-запросов сверяйте по доке или зовите через `ms_call_raw`). Подробности — в
> разделе «Оговорки».

## Зачем это нужно

Учёт живёт в МойСклад, а ИИ-ассистент обычно бесполезен: либо ходит через браузер
и спотыкается, либо выдумывает цифры, которые звучат уверенно. `moysklad-mcp-ru`
даёт агенту **прямой доступ к JSON API 1.2** вашего аккаунта:

- **Числа из реального API, а не из головы модели.** Остатки, заказы, прибыль,
  обороты — это ответ МойСклад, с источником и полями.
- **Запись за двумя гейтами.** Создание документа делает ЧЕРНОВИК; проведение
  (двигает учёт) — отдельный destructive-шаг с подтверждением. Запись вообще
  выключена, пока её явно не включить и не направить на тестовый кабинет.
- **Без браузера.** Прямые HTTPS-вызовы по токену кабинета.

Скажите агенту обычными словами: «покажи остатки», «что пора дозаказать»,
«создай приёмку на 10 Рога от поставщика» — он подберёт метод или сценарий.

## Что внутри

**Не «один тул на эндпоинт», а 8 generic мета-тулов над каталогом** — полное
покрытие API при маленькой поверхности.

```
ваш ИИ-агент
      │
      ▼
 8 мета-тулов  ──►  каталог (endpoints.yaml)  ──►  общий core
 search / describe /                                клиент · safety · ошибки
 call / call_raw /                                  пагинация · реестр
 fetch_all / map / ...                                    │
 + типизированные тулы (ms_get_stock, ms_create_document, …)  ▼
                                              МойСклад JSON API 1.2 (HTTPS)
```

**Мета-тулы** (`ms_search_methods`, `ms_describe_method`, `ms_call_method`,
`ms_call_raw`, `ms_fetch_all`, `ms_map`, + тулы кабинетов).

**Типизированные read-тулы:** `ms_get_stock`, `ms_get_products`, `ms_get_orders`,
`ms_get_profit`, `ms_get_money`, `ms_get_turnover`, `ms_get_counterparties`,
`ms_get_stores`, `ms_get_documents` (7 типов), `ms_ping`. Копейки автоматически
переводятся в рубли.

**Тулы записи (за двумя гейтами):**

| Тул | Уровень | Назначение |
|---|---|---|
| `ms_build_document` | read | Preview ЛЮБОГО типа: резолв ссылок + точное тело, БЕЗ записи. |
| `ms_create_document` | write | Создать ЛЮБОЙ ролевой тип ЧЕРНОВИКОМ (`applicable:false`). |
| `ms_build_purchaseorder` / `ms_create_purchaseorder` | read / write | Типизированный заказ поставщику (для совместимости). |
| `ms_post_document` | destructive | Провести документ (`applicable:true`) — двигает учёт. |
| `ms_delete_document` | destructive | Удалить документ (уборка). |

7 ролевых типов: `purchaseorder`, `supply`, `demand`, `invoicein`, `invoiceout`,
`salesreturn`, `purchasereturn`.

**Каталог — schema-driven из официальной доки МойСклад:** 892 метода (курированное
ядро выверено живьём; остальное импортировано из доки). `ms_call_raw` достаёт всё,
чего ещё нет в каталоге.

## Что можно спросить

```
покажи остатки и что пора дозаказать
вытащи прибыль по товарам за прошлый месяц
кто из контрагентов должен нам денег
создай черновик приёмки: 10 «Рога» от «ООО Поставщик» по 250 ₽   (на тестовом кабинете)
проведи эту приёмку и покажи, как изменился остаток
```

Не уверены, с чего начать — скажите **«что ты умеешь по моему кабинету»** или
вызовите `ms_map`.

## Safety model

Токен кабинета двигает остатки и деньги. Каждый метод классифицирован:

- **read** → выполняется сразу;
- **write** (создать черновик) → требует `confirm_write=true` **И** включённой
  записи `MOYSKLAD_ALLOW_WRITE=1`;
- **destructive** (провести / удалить) → ещё и `i_understand_this_modifies_data=true`.

**Два независимых слоя:** (1) процессный guard (`MOYSKLAD_ALLOW_WRITE`, по умолчанию
ВЫКЛ, опц. пин к кабинету `MOYSKLAD_WRITE_CABINETS`) — защита от направления на
боевой кабинет; (2) per-call гейт. Guard покрывает и сырые `ms_call_method`/
`ms_call_raw`, не только типизированные тулы. **0 мутаций, помеченных как read** —
проверяется тестом (`test_safety_catalog`) в CI. Создание всегда делает ЧЕРНОВИК;
проведение — отдельный шаг.

## Установка

Подробный гайд — в **[QUICKSTART.md](QUICKSTART.md)**. Три пути, один результат:

1. **Проще всего — попроси своего ИИ (без терминала).** Открой Claude / Cowork и
   скажи: *«установи МойСклад MCP»* — агент проведёт по встроенному `moysklad-mcp-install/`.
2. **Скачать и кликнуть.** Возьми release-zip, распакуй, двойной клик
   `install.command` (macOS) / `install.bat` (Windows), вставь токен.
3. **Технический.** `python3 install.py --client <твой-клиент>` (claude-desktop /
   claude-code / codex / opencode).
4. **Для разработчиков.** Пакет на PyPI — запуск без установки: `uvx moysklad-mcp-ru`.
   Для Claude Desktop — готовый `.mcpb`-бандл из
   [релиза](https://github.com/ilyautov/moysklad-mcp-ru/releases) (двойной клик,
   токен вводится в окне настроек). Полный список каналов и как режется релиз —
   в **[docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)**.

Для путей 1–3 не нужно ни `pip install`, ни правки JSON: зависимости ставятся сами
при первом запуске (локальный venv), от тебя — только токен.

**Где взять токен:** МойСклад → Настройки → Пользователи → Токены доступа. Токен
хранится в `~/.moysklad-mcp/cabinets.json` (локально, chmod 600, никогда в репо
и не в чат). Поддержка **мультикабинета** — несколько аккаунтов с переключением из
чата (`ms_add_cabinet` / `ms_use_cabinet`).

**Проверка после установки.** Поставили пакетом (`uvx`, `pip`): `moysklad-mcp-ru doctor` — печатает версию, число инструментов, размер каталога и состояние гейта записи, в сеть не ходит. Работаете из клона: `python3 serve.py ms --selfcheck` → «OK: ms ready, N tools».

## Деньги

Все суммы в API — в копейках. Read-тулы отдают рубли. На записи
`convert_money_to_kopecks` переводит цены/суммы рубли→копейки (`price` позиции,
`sum`, price-объекты). Сырые мета-тулы работают в копейках как есть.

## Выверено боем

- Хост `api.moysklad.ru/api/remap/1.2`, списки в `rows`, offset+limit (макс 1000).
- Лимит: бакет **45/3с**, окно 3000 мс, тяжёлый отчёт остатков весит 5 единиц.
- Жёстко: `Accept: application/json;charset=utf-8` ровно (иначе 400 код 1062),
  `Accept-Encoding: gzip` (иначе 415).
- **Запись (демо-кабинет):** веер create→read-back→проведение→движение остатков→
  удаление→откат на всех 6 ролевых типах + purchaseorder. Деньги ×100 верны,
  supply/salesreturn +, demand/purchasereturn −, счета не двигают, удаление
  откатывает, возвраты создаются standalone.

## Оговорки (сверяйте с живой докой)

- **Импортированные из доки методы: пути надёжны, тела write — нет.** Считайте их
  картой разведки: подтверждайте по доке или зовите через `ms_call_raw`.
  Курированное ядро и срез записи — надёжны.
- **Кабинет затеняет env:** активный кабинет в `cabinets.json` приоритетнее
  переменных окружения. Необъяснимый 401 — первым делом проверьте стор.
- **Запись только на тестовый кабинет.** Не направляйте `MOYSKLAD_ALLOW_WRITE=1` на
  боевой учёт, пока сами не проверите на тесте.

## Структура

```
core/                 ← вендорный движок ilyautov/marketplaces-mcp-ru (MIT, не менялся)
moysklad_mcp/         ← специфика МойСклад: server.py, build.py, money.py, refs.py,
                        write_guard.py, endpoints.yaml(+curated), workflows.yaml, entities.yaml
tests/                ← 70 офлайн-тестов
scripts/              ← ingest_moysklad.py (парсер доки), package_release.py
serve.py              ← лаунчер (авто-venv): python3 serve.py ms [--selfcheck]
install.py + .command/.bat/.sh + moysklad-mcp-install/   ← установка под 4 клиента
.mcp.json + .claude-plugin/ .codex-plugin/ .cursor-plugin/   ← плагин-манифесты
docs/                 ← исследование, аудит, RUNBOOK-и, точки возобновления (dev-доки)
```

## Лицензия

MIT. Вендорный `core/` — под MIT Ильи Утова, см. [`NOTICE`](NOTICE). Архитектура
(schema-driven каталог, safety-гейт, единые ошибки, авто-п