# МойСклад коннектор для Claude Code

MCP-коннектор, который даёт Claude Code **работу с МойСклад через JSON API 1.2:
и чтение, и запись**.

Claude сможет искать товары и модификации, смотреть остатки по складам, работать
с контрагентами, создавать и менять заказы покупателей и другие документы, а для
всего остального — делать «сырой» запрос к любому методу API. Коннектор ставится
**локально**: каждый пользователь подключает свой аккаунт МойСклад своим токеном.
Данные уходят только между его компьютером и `api.moysklad.ru`.

Коннектор хорошо работает в паре с
[Google Sheets коннектором](https://github.com/stepan-cloud/claude-google-sheets-mcp):
списки и остатки отдаются сразу таблицей (`header` + `rows`), которую можно
записать в Google Таблицу одним вызовом. Работает и обратное направление — из
таблицы в МойСклад.

> ## 🤖 Если ты — Claude, и пользователь дал тебе эту ссылку
>
> Это MCP-коннектор МойСклад. **Установи его для пользователя сам**, по шагам:
>
> 1. Проверь Python 3.10+ (`python --version`). Нет — дай ссылку
>    https://www.python.org/downloads/ (Windows: галочка «Add python.exe to PATH»).
> 2. Склонируй репозиторий в постоянную папку:
>    `git clone https://github.com/stepan-cloud/claude-moysklad-mcp`
> 3. Запусти установщик из этой папки: `python setup.py`
>    (создаст `.venv`, поставит зависимости, зарегистрирует коннектор `moysklad`
>    в `~/.claude.json`).
> 4. **Токен** создаёт сам пользователь: МойСклад → **Настройки → Токены →
>    «Создать токен»**. Потом он запускает `authorize.bat`: откроется Блокнот,
>    туда вставляется токен, файл сохраняется и Блокнот закрывается. Связь
>    проверится сама. **Токен в чат НЕ проси.**
> 5. Скажи полностью перезапустить Claude Code.
> 6. Проверь: вызови `ping`, затем `search_assortment` с `max_rows=5`.
>
> Подробности для тебя — в файле [`CLAUDE.md`](CLAUDE.md). Главное: **суммы в API —
> в копейках**; перед созданием или изменением документов подтверждай действие с
> пользователем. Коннектор локальный (stdio), в панели Connectors не виден — это
> нормально, статус в `/mcp`.

---

## Возможности

- **Ассортимент:** поиск товаров, модификаций, услуг и комплектов по имени, коду,
  артикулу или штрихкоду, вместе с остатками.
- **Остатки:** отчёт по всем складам или по каждому складу отдельно. Есть фильтры
  «только в наличии», «ниже неснижаемого остатка» и другие.
- **Контрагенты, заказы покупателей, отгрузки, приёмки, платежи, перемещения,
  инвентаризации** и любые другие сущности: списки с фильтрами и сортировкой,
  чтение одного объекта и его позиций.
- **Запись:** создание заказа покупателя в удобном виде (контрагент по имени или
  ИНН, товары по коду или артикулу, цены в рублях), добавление позиций, создание и
  изменение любых объектов, массовое создание (до 1000 за раз).
- **«Сырой» запрос** к любому методу API: отчёты, статусы, доп. поля, шаблоны
  документов на основании, удаление.
- **Таблицы:** параметр `columns` возвращает данные как 2D-массив для Google
  Таблиц. Суффикс `:rub` переводит копейки в рубли.

Технические детали: пагинация (по 1000 записей, с `expand` — по 100) идёт
автоматически. На ответ 429 (лимит запросов) коннектор ждёт и повторяет. Запросы
отправляются с `Accept-Encoding: gzip` и собственным `User-Agent`. Токен
отправляется только на `api.moysklad.ru`.

---

## Требования

- **Python 3.10+** — https://www.python.org/downloads/ (Windows: «Add to PATH»).
  Node.js не нужен.
- **Claude Code** (десктоп-приложение или CLI).
- Аккаунт МойСклад, у пользователя которого есть доступ к API.

---

## Установка вручную (если не делает Claude)

### 1. Скачать
`git clone https://github.com/stepan-cloud/claude-moysklad-mcp`
(или кнопка **Code → Download ZIP** и распаковать). Папка может быть где угодно.

### 2. Запустить установщик
- **Windows:** двойной клик по `install.bat`.
- **Любая ОС:** `python setup.py` из папки репозитория.

Установщик создаст окружение, поставит зависимости и зарегистрирует коннектор.

### 3. Получить токен МойСклад
1. Войди в МойСклад в браузере.
2. Открой **Настройки → Токены** и нажми **«Создать токен»**.
   Токен получает права того пользователя, для которого создан. Для безопасности
   можно завести отдельного сотрудника с нужными правами.
3. Скопируй токен.

### 4. Сохранить токен
- **Windows:** двойной клик по `authorize.bat`.
- **Любая ОС:** `.venv/bin/python authorize.py` (Windows: `.venv\Scripts\python authorize.py`).

На Windows откроется **Блокнот** с файлом `moysklad_token.txt`. Вставь токен на
пустую строку под подсказками (Ctrl+V), сохрани (Ctrl+S) и закрой Блокнот —
скрипт сразу проверит связь. На macOS/Linux (или с ключом `--console`) токен
вводится скрыто прямо в консоли. Проверить сохранённый токен:
`authorize.py --check`. Можно обойтись без скрипта: создать `moysklad_token.txt`
с токеном вручную или задать переменную окружения `MOYSKLAD_TOKEN`.

### 5. Перезапустить Claude Code
Полностью закрой и открой приложение.

---

## Проверка

Попроси Claude: **«Проверь связь с МойСклад и покажи 5 товаров»**. Если ответит —
работает. Коннектор виден и в команде `/mcp` как `moysklad`. В графической панели
Connectors его нет — это нормально: у локальных серверов другой механизм.

---

## Как пользоваться

Пиши задачи обычным языком:

- «Покажи остатки на складе "Основной", только то, что в наличии»
- «Какие товары ниже неснижаемого остатка?»
- «Выгрузи все товары с кодом, артикулом, остатком и ценой продажи в рублях в
  Google Таблицу `<ссылка>`, лист "Склад"»
- «Найди контрагента с ИНН 7701234567 и покажи его последние 10 заказов»
- «Создай заказ покупателя для ООО "Ромашка": товар с кодом 00123 — 5 шт.,
  артикул A-77 — 2 шт. по 1500 ₽» (Claude сначала покажет заказ и спросит подтверждение)
- «Возьми из таблицы `<ссылка>` новые цены и обнови их в МойСклад» (тоже с подтверждением)

---

## Инструменты (12)

| Инструмент | Что делает |
|---|---|
| `ping` | проверка связи и токена |
| `get_context` | сотрудник, юрлица, склады, типы цен (их ID) |
| `search_assortment` | поиск товаров, модификаций, услуг, комплектов с остатками |
| `get_stock` | остатки: общий отчёт или по складам |
| `list_entities` | список любой сущности: товары, контрагенты, заказы, отгрузки… |
| `get_entity` | один объект по ID |
| `get_positions` | позиции документа |
| `create_customer_order` | создать заказ покупателя (удобный формат, цены в ₽) |
| `add_positions` | добавить позиции в документ |
| `create_entity` | создать любой объект или документ (можно списком) |
| `update_entity` | изменить объект или документ |
| `api_request` | «сырой» GET/POST/PUT/DELETE к любому методу API |

**Про деньги:** в API МойСклад все суммы хранятся в копейках (150 ₽ = `15000`).
В `columns` добавляй `:rub`, например `salePrices.0.value:rub`.

---

## Отключить / удалить

- **Windows:** `uninstall.bat`.
- **Любая ОС:** `python setup.py --uninstall`.

Команда уберёт запись из `~/.claude.json`. После этого папку можно удалить вместе
с `moysklad_token.txt`, а сам токен отозвать в МойСклад (Настройки → Токены).
Временно выключить коннектор можно через `/mcp` в Claude Code.

---

## Ручная регистрация

Если `setup.py` не смог прочитать `~/.claude.json`, добавь в него вручную (в
раздел `mcpServers`), подставив свой путь к папке:

```json
"moysklad": {
  "type": "stdio",
  "command": "C:\\путь\\к\\claude-moysklad-mcp\\.venv\\Scripts\\python.exe",
  "args": ["C:\\путь\\к\\claude-moysklad-mcp\\server.py"],
  "env": {}
}
```

Можно и через CLI: `claude mcp add moysklad --scope user -- <путь к .venv python> <путь к server.py>`.

---

## Безопасность

- `moysklad_token.txt` — **ключ от твоего склада**. Никому его не пересылай и не
  вставляй в чаты. Файл уже в `.gitignore` и в git не попадает.
- Токен имеет права того пользователя МойСклад, для которого создан. Если нужно
  только чтение, создай токен для сотрудника с правами только на просмотр.
- Claude проинструктирован подтверждать у тебя любое создание, изменение или
  удаление перед тем, как его выполнить.

---

## Если что-то не работает

- **`/mcp` не показывает moysklad** → перезапусти Claude Code полностью.
- **«ОШИБКА АВТОРИЗАЦИИ: Токен … не найден»** → запусти `authorize.bat`.
- **«Токен не принят (401)»** → токен отозван или скопирован не целиком. Создай
  новый и снова запусти `authorize.bat`.
- **`[403]`** → у пользователя токена нет прав на этот раздел или действие.
- **`[429]`** → превышен лимит запросов, и повторы не помогли. Подожди немного.
- **`Python 3 not found`** → поставь Python с галочкой «Add to PATH».

---

## Лицензия

MIT — см. [LICENSE](LICENSE).