moysklad-mcp-ru

moysklad-mcp-ru: Acesso por IA ao МойСклад para Claude Code, Cursor, Codex e Cowork

🇬🇧 English version

Você mantém a contabilidade no МойСклад — dê ao seu IA acesso direto à sua conta. Um servidor MCP sobre a JSON API 1.2 do МойСклад: saldos, produtos, pedidos, contrapartes, relatórios (lucro, faturamento, dinheiro) e gravação de documentos (recebimentos, remessas, pedidos, faturas, devoluções) — diretamente pela API, sem navegador. Os números vêm da API real, não são inventados pelo modelo. Dois portões de gravação impedem a criação ou lançamento acidental de documentos na contabilidade de produção. Auto-paginação, multi-cabine, busca em russo. Para Claude Code, Cursor, Codex, Cowork e Claude Desktop.

Início rápido, sem instalação no sistema:

uvx moysklad-mcp-ru

Clientes, token e a forma de "peça ao seu IA para instalar": na seção «Instalação».

⚠️ alpha. Ajuda com a operação contábil, mas é uma ferramenta, não um substituto para contador. O núcleo curado e o recorte de gravação foram testados em cabine de teste; métodos importados da documentação — mapa para exploração (caminhos confiáveis, corpos de write-requests confira na documentação ou chame via ms_call_raw). Detalhes — na seção "Ressalvas".

Por que isso é necessário

A contabilidade vive no МойСклад, e o assistente de IA geralmente é inútil: ou navega pelo navegador e tropeça, ou inventa números que soam confiantes. moysklad-mcp-ru dá ao agente acesso direto à JSON API 1.2 da sua conta:

• Números da API real, não da cabeça do modelo. Saldos, pedidos, lucro, faturamento — é a resposta do МойСклад, com fonte e campos.
• Gravação atrás de dois portões. A criação de documento faz um RASCUNHO; o lançamento (movimenta a contabilidade) — é uma etapa destrutiva separada com confirmação. A gravação fica desligada até ser explicitamente ativada e direcionada para a cabine de teste.
• Sem navegador. Chamadas HTTPS diretas com o token da cabine.

Diga ao agente em palavras comuns: "mostre os saldos", "o que está na hora de reencomendar", "crie um recebimento de 10 Roga do fornecedor" — ele escolherá o método ou cenário.

O que tem dentro

Não é "uma ferramenta por endpoint", mas 8 meta-ferramentas genéricas sobre o catálogo — cobertura completa da API com uma superfície pequena.

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

Meta-ferramentas (ms_search_methods, ms_describe_method, ms_call_method, ms_call_raw, ms_fetch_all, ms_map, + ferramentas de cabines).

Ferramentas de leitura tipadas: 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 tipos), ms_ping. Centavos são automaticamente convertidos em rublos.

Ferramentas de gravação (atrás de dois portões):

Ferramenta	Nível	Finalidade
ms_build_document	read	Preview de QUALQUER tipo: resolução de links + corpo exato, SEM gravação.
ms_create_document	write	Criar QUALQUER tipo de papel como RASCUNHO (applicable:false).
ms_build_purchaseorder / ms_create_purchaseorder	read / write	Pedido tipado ao fornecedor (para compatibilidade).
ms_post_document	destructive	Lançar documento (applicable:true) — movimenta a contabilidade.
ms_delete_document	destructive	Excluir documento (limpeza).

7 tipos de papel: purchaseorder, supply, demand, invoicein, invoiceout, salesreturn, purchasereturn.

Catálogo — schema-driven da documentação oficial do МойСклад: 892 métodos (núcleo curado verificado ao vivo; o restante importado da documentação). ms_call_raw busca tudo que ainda não está no catálogo.

O que se pode perguntar

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

Não sabe por onde começar — diga "o que você sabe fazer na minha cabine" ou chame ms_map.

Modelo de segurança

O token da cabine movimenta saldos e dinheiro. Cada método é classificado:

• read → executa imediatamente;
• write (criar rascunho) → exige confirm_write=true E gravação ativada MOYSKLAD_ALLOW_WRITE=1;
• destructive (lançar / excluir) → também i_understand_this_modifies_data=true.

Duas camadas independentes: (1) guard de processo (MOYSKLAD_ALLOW_WRITE, por padrão DESLIGADO, opcionalmente pin para cabine MOYSKLAD_WRITE_CABINETS) — proteção contra direcionamento para cabine de produção; (2) portão por chamada. O guard cobre também ms_call_method/ ms_call_raw brutos, não apenas ferramentas tipadas. 0 mutações marcadas como read — verificado por teste (test_safety_catalog) no CI. A criação sempre faz RASCUNHO; o lançamento — é uma etapa separada.

Instalação

Guia detalhado — em QUICKSTART.md. Três caminhos, um resultado:

1. O mais simples — peça ao seu IA (sem terminal). Abra Claude / Cowork e diga: "instale o МойСклад MCP" — o agente conduzirá pelo moysklad-mcp-install/ embutido.
2. Baixar e clicar. Pegue o release-zip, descompacte, clique duas vezes em install.command (macOS) / install.bat (Windows), cole o token.
3. Técnico. python3 install.py --client <твой-клиент> (claude-desktop / claude-code / codex / opencode).
4. Para desenvolvedores. Pacote no PyPI — execução sem instalação: uvx moysklad-mcp-ru. Para Claude Desktop — bundle .mcpb pronto do release (clique duplo, token inserido na janela de configurações). Lista completa de canais e como o release é cortado — em docs/DISTRIBUTION.md.

Para os caminhos 1–3 não é necessário pip install, nem editar JSON: as dependências são instaladas sozinhas no primeiro início (venv local), de você — só o token.

Onde obter o token: МойСклад → Configurações → Usuários → Tokens de acesso. O token é armazenado em ~/.moysklad-mcp/cabinets.json (localmente, chmod 600, nunca no repositório e nem no chat). Suporte a multi-cabine — várias contas com alternância pelo chat (ms_add_cabinet / ms_use_cabinet).

Verificação após a instalação. Instalou pelo pacote (uvx, pip): moysklad-mcp-ru doctor — imprime a versão, o número de ferramentas, o tamanho do catálogo e o estado do portão de gravação, não acessa a rede. Trabalha a partir do clone: python3 serve.py ms --selfcheck → "OK: ms ready, N tools".

Dinheiro

Todos os valores na API — em centavos. As ferramentas de leitura retornam rublos. Na gravação, convert_money_to_kopecks converte preços/valores rublos→centavos (price posições, sum, objetos price). As meta-ferramentas brutas trabalham em centavos como estão.

Verificado em batalha

• Host api.moysklad.ru/api/remap/1.2, listas em rows, offset+limit (máx. 1000).
• Limite: bucket 45/3s, janela 3000 ms, relatório pesado de saldos pesa 5 unidades.
• Rigorosamente: Accept: application/json;charset=utf-8 exatamente (senão 400 código 1062), Accept-Encoding: gzip (senão 415).
• Gravação (cabine de demonstração): leque create→read-back→lançamento→movimentação de saldos→ exclusão→rollback em todos os 6 tipos de papel + purchaseorder. Dinheiro ×100 correto, supply/salesreturn +, demand/purchasereturn −, faturas não movimentam, exclusão faz rollback, devoluções são criadas standalone.

Ressalvas (confira com a documentação viva)

• Métodos importados da documentação: caminhos confiáveis, corpos de write — não. Considere-os um mapa de exploração: confirme pela documentação ou chame via ms_call_raw. O núcleo curado e o recorte de gravação — confiáveis.
• A cabine sobrepõe o env: cabine ativa em cabinets.json tem prioridade sobre variáveis de ambiente. 401 inexplicável — primeiro verifique o store.
• Gravação apenas na cabine de teste. Não direcione MOYSKLAD_ALLOW_WRITE=1 para a contabilidade de produção antes de verificar você mesmo no teste.

Estrutura

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-доки)

Licença

MIT. Vendor core/ — sob MIT de Ilya Utov, veja NOTICE. A arquitetura (catálogo schema-driven, portão de segurança, erros unificados, auto-paginação) reutiliza as ideias mais fortes de marketplaces-mcp-ru.

Encontrou um problema — abra uma issue. Isso é alpha e código aberto: instale, teste com seus dados, experimente.

---

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

---

Quem fez isso

Ilya Utov, laboratório AI Frontier. Como essas ferramentas funcionam internamente, escrevo no Telegram e LinkedIn.

Também disponíveis:

• humanizer-ru: remove vestígios de rede neural de texto em russo
• marketplaces-mcp-ru: Wildberries, Ozon, Yandex Market e Avito direto do agente
• small-business-ru: 34 habilidades para pequenas empresas, calculam impostos e verificam contraparte por INN
• consilium-principis: conselho de pensadores, onde cada citação é verificada literalmente
• hefest: segurança química de fábrica, totalmente offline

Todos os projetos em uma lista, organizados por finalidade: ilyautov.github.io. Código-fonte: github.com/ilyautov. Se foi útil, dê uma estrela: é assim que outros encontram.