MoySklad MCP (RU)

Name: MoySklad MCP (RU)
Author: ilyautov

本地服务

moysklad-mcp-ru.aifrontier.tech商业与营销33 周前更新

代码仓库访问官网

关于 MoySklad MCP (RU)

面向使用 МойСклад 的团队，这个 MCP 服务通过 JSON API 1.2 提供库存、商品、订单、报表和单据操作。Schema 驱动的工具目录覆盖广泛，并用双重安全门限制写入与过账。

主要功能

01查询库存、商品、订单与往来方
02获取利润、资金和周转报表
03Schema 驱动的 API 方法目录
04创建单据草稿并预览写入内容
05双重确认控制写入、过账和删除
06支持多个 кабинеты 切换

适用场景

01查看库存并判断补货需求
02分析商品利润或资金周转
03为采购或发货创建单据草稿
04在测试账户验证单据过账影响

MCP 相关

作为 MCP 服务，它向 AI 客户端提供 МойСклад JSON API 的元工具和类型化工具，涵盖查询、写入与单据操作。写入默认关闭，草稿创建、过账和删除受分级安全门控制。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "ilyautov-moysklad-mcp-ru": {
      "command": "uvx",
      "args": [
        "moysklad-mcp-ru"
      ],
      "env": {
        "MOYSKLAD_TOKEN": "<MOYSKLAD_TOKEN>",
        "MOYSKLAD_ALLOW_WRITE": "<MOYSKLAD_ALLOW_WRITE>"
      }
    }
  }
}

启动命令uvx moysklad-mcp-ru

需要配置的环境变量

MOYSKLAD_TOKEN密钥MoySklad personal access token (Настройки → Пользователи → Токены доступа). Optional if credentials are stored in ~/.moysklad-mcp/cabinets.json.

MOYSKLAD_ALLOW_WRITESet to 1 to allow document writes (create/post/delete). Off by default. Point only at a TEST cabinet.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypimoysklad-mcp-ru0.2.0stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

moysklad-mcp-ru：为 Claude Code、Cursor、Codex 和 Cowork 提供 AI 访问 МойСклад 的能力

🇬🇧 英文版

在 МойСклад 中管理账目？让 AI 直接访问您的账户。 一个基于 МойСклад JSON API 1.2 的 MCP 服务：库存、商品、订单、往来单位、报表（利润、营业额、资金）以及单据写入（收货、发货、订单、发票、退货）——通过 API 直接操作，无需浏览器。数值来自真实 API，而非模型编造。两道写入关卡可避免意外创建或过账正式账目中的单据。自动分页、多账户、俄语搜索。适用于 Claude Code、Cursor、Codex、Cowork 和 Claude Desktop。

快速开始，无需安装到系统中：

uvx moysklad-mcp-ru

客户端、令牌以及“让 AI 帮你安装”的方法，请参阅“安装”。

⚠️ alpha。 可协助处理账目运营工作，但它只是工具，不能替代会计师。经过精选的核心功能和写入部分已在测试账户中实战验证；从文档导入的方法只是探索指南（路径可靠，写入请求的请求体请对照文档核实，或通过 raw 工具调用）。详情请参阅“注意事项”部分。

为什么需要它

账目记录在 МойСклад 中，而 AI 助手通常派不上用场：要么通过浏览器操作时频频出错，要么编造听起来很可信的数字。moysklad-mcp-ru 让 Agent 直接访问您账户的 JSON API 1.2：

数据来自真实 API，而不是模型的想象。 库存、订单、利润、营业额——这些都是 МойСклад 返回的结果，包含来源和字段。
写入操作设有两道关卡。 创建单据会生成草稿；过账（会改变账目）是另一个破坏性步骤，需要确认。写入功能默认关闭，只有明确启用并指向测试账户后才可使用。
无需浏览器。 使用账户令牌直接发起 HTTPS 调用。

用日常语言告诉 Agent：“显示库存”“哪些商品该补货了”“为供应商创建一张 10 个角的收货单”——它会选择合适的方法或工作流。

包含内容

不是“每个端点一个工具”，而是在目录之上提供 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。戈比会自动换算成卢布。

写入工具（需通过两道关卡）：

工具	级别	用途
`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。

目录由 MoySklad 官方文档驱动生成 schema： 892 个方法（经过实测验证的精选核心；其余从文档导入）。ms_get_raw 可获取目录中尚未收录的所有内容。

可以询问什么

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

不确定从哪里开始——请说 “我的账户能做什么”，或调用 ms_map。

安全模型

账户令牌可以影响库存和资金。每种方法都经过分类：

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）每次调用的关卡。Guard 同样覆盖原始的 ms_call_method/raw 工具，而不只是类型化工具。没有任何被标记为 read 的变更操作——CI 中通过测试（test_safety_catalog）验证。创建操作始终生成草稿；过账是单独的步骤。

安装

详细指南请参阅 QUICKSTART.md。三种方式，结果相同：

最简单——让你的 AI 帮你安装（无需终端）。 打开 Claude / Cowork 并说：“安装 MoySklad MCP”——Agent 会通过内置的 moysklad-mcp-install/ 引导你完成安装。
下载并点击。 获取 release-zip，解压后双击 install.command（macOS）/ install.bat（Windows），再粘贴令牌。
技术方式。 python3 install.py --client <你的客户端>（claude-desktop / claude-code / codex / opencode）。
面向开发者。 PyPI 上的软件包——无需安装即可运行：uvx moysklad-mcp-ru。 Claude Desktop 可使用 release 中现成的 .mcpb 捆绑包（双击即可，在设置窗口中输入令牌）。完整的分发渠道列表及 release 的裁剪方式，请参阅 docs/DISTRIBUTION.md。

方式 1–3 均无需 pip install，也无需编辑 JSON：首次启动时会自动安装依赖（本地 venv），你只需提供令牌。

获取令牌： MoySklad → 设置 → 用户 → 访问令牌。令牌存储在 ~/.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. Пригодилось, поставьте звезду: по ней это находят другие.

支持 Markdown

登录后评论