MoySklad MCP (RU)

moysklad-mcp-ru：Claude Code、Cursor、Codex、Cowork 向けのМойСклад AI アクセス

🇬🇧 英語版

МойСкладで帳簿を管理しているなら、AIにアカウントへの直接アクセスを許可しましょう。 МойСклад JSON API 1.2 を利用する単一の MCP サーバーです。在庫、商品、注文、取引先、 レポート（利益、売上高、資金）に加え、伝票の作成（入庫、出荷、 注文、請求書、返品）にも、ブラウザーを使わずAPIから直接アクセスできます。数値は モデルが作り出したものではなく、実際のAPIから取得します。書き込み時の2段階ゲートにより、本番の帳簿に誤って伝票を作成したり処理したりすることを防ぎます。自動ページネーション、 複数アカウント対応、日本語での検索。Claude Code、Cursor、Codex、Cowork、Claude Desktop 向けです。

クイックスタート（システムへのインストール不要）：

uvx moysklad-mcp-ru

クライアント、トークン、AIにインストールを頼む方法については、「インストール」のセクションをご覧ください。

⚠️ アルファ版です。 帳簿管理の業務を支援するツールですが、会計士の代わりにはなりません。厳選したコア機能と書き込み機能は、テスト用アカウントでの実運用を通じて検証済みです。 ドキュメントから取り込んだメソッドは調査用の地図です（パスは信頼できますが、書き込みリクエストの本文はドキュメントで確認するか、rawツールを使ってください）。詳細は「注意事項」のセクションをご覧ください。

これが必要な理由

帳簿はМойСкладで管理されているのに、AIアシスタントはたいてい役に立ちません。ブラウザー経由でアクセスしてつまずくか、自信ありげに聞こえる数値をでっち上げるかのどちらかです。moysklad-mcp-ru を使うと、エージェントにアカウントのJSON API 1.2への直接アクセスを提供できます。

• モデルの推測ではなく、実際のAPIから取得した数値です。 在庫、注文、利益、 売上高などは、出典とフィールドを含むМойСкладの応答です。
• 2段階のゲートを通じた書き込み。 伝票を作成すると下書きになります。処理（帳簿を動かす操作）は、確認が必要な別個の破壊的操作です。書き込みは明示的に有効化し、テスト用アカウントに接続するまで無効です。
• ブラウザー不要。 アカウントのトークンを使ったHTTPSの直接呼び出しです。

エージェントに「在庫を見せて」「そろそろ追加注文が必要なのは何？」「仕入先からロガを10個入庫する伝票を作成して」のように普段の言葉で頼めば、適切なメソッドやシナリオを選んでくれます。

内容

「エンドポイントごとに1つのツール」ではなく、カタログ全体を扱う10個の汎用メタツール — 小さなインターフェースでAPIを完全にカバーします。

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

メタツール（ms_search_methods、ms_describe_method、ms_call_method、 ms_write_method、ms_delete_method、ms_get_raw、ms_write_raw、 ms_delete_raw、ms_fetch_all、ms_map、＋キャビネット用ツール）。

型付きの読み取りツール： 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。コペイカは自動的に ルーブルに換算されます。

書き込みツール（2つのゲートで保護）：

ツール	レベル	用途
ms_build_document	read	あらゆる種類のプレビュー：参照の解決と正確なリクエスト本文の作成。書き込みは行いません。
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。

カタログは公式のМойСкладドキュメントに基づくスキーマ駆動型です： 892メソッド （厳選された中核部分は実環境で検証済みで、残りはドキュメントから取り込んでいます）。ms_get_rawで、 カタログにまだないものも取得できます。

質問できること

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

何から始めればよいかわからない場合は、**「自分のキャビネットで何ができる？」**と尋ねるか、 ms_mapを呼び出してください。

安全モデル

キャビネットのトークンを使うと、在庫と金額が変更される可能性があります。各メソッドは次のように分類されています。

• read → そのまま実行されます。
• write（下書きの作成）→ confirm_write=true かつ 書き込み設定 MOYSKLAD_ALLOW_WRITE=1が必要です。
• destructive（確定／削除）→ さらにi_understand_this_modifies_data=trueが必要です。

独立した2つのレイヤー： （1）プロセスガード（MOYSKLAD_ALLOW_WRITE。デフォルトは オフ。オプションでキャビネットをピン留めするMOYSKLAD_WRITE_CABINETS）— 本番 キャビネットへの誤操作を防ぎます。（2）呼び出しごとのゲート。ガードは型付きツールだけでなく、 生のms_call_methodやrawツールも対象です。readとしてマークされた変更操作は0件 — CIでテスト（test_safety_catalog）によって確認されます。作成時には必ず下書きが作られ、 確定は別の手順です。

インストール

詳しいガイドは**QUICKSTART.md**をご覧ください。3つの方法で、結果は同じです。

1. 最も簡単 — AIに頼む（ターミナル不要）。 Claude / Coworkを開いて *「МойСклад MCPをインストールして」*と伝えると、エージェントが組み込みのmoysklad-mcp-install/を使って案内します。
2. ダウンロードしてクリック。 リリース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バンドルを使えます（ダブルクリックして、設定画面でトークンを入力）。 配布チャンネルの一覧とリリースの作成方法は**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 — нет. Считайте их картой разведки: подтверждайте по доке или зовите через 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. Архитектура (schema-driven каталог, safety-гейт, единые ошибки, авто-пагинация) переиспользует сильнейшие идеи marketplaces-mcp-ru.

Нашли косяк — заводите issue. Это alpha и открытый код: ставьте, проверяйте на своих данных, экспериментируйте.

---

mcp-name: io.github.ilyautov/moysklad-mcp-ru

---

Кто это сделал

Илья Утов, лаборатория AI Frontier. Как эти инструменты устроены внутри, пишу в Telegram и LinkedIn.

Рядом стоят:

• humanizer-ru: убирает следы нейросети из русского текста
• marketplaces-mcp-ru: Wildberries, Ozon, Яндекс Маркет и Авито прямо из агента
• small-business-ru: 34 скилла для малого бизнеса, считают налоги и проверяют контрагента по ИНН
• consilium-principis: совет мыслителей, где каждая цитата сверяется дословно
• hefest: химическая безопасность завода, целиком офлайн

Все проекты одним списком, разобранные по назначению: ilyautov.github.io. Исходники: github.com/ilyautov. Пригодилось, поставьте звезду: по ней это находят другие.