moysklad-mcp-ru

moysklad-mcp-ru: Acceso por IA a MoySklad para Claude Code, Cursor, Codex y Cowork

🇬🇧 Versión en inglés

¿Llevas la contabilidad en MoySklad? Dale a la IA acceso directo a tu cuenta. Un servidor MCP sobre la JSON API 1.2 de MoySklad: existencias, productos, pedidos, contrapartes, informes (beneficios, facturación, dinero) y registro de documentos (recepciones, envíos, pedidos, facturas, devoluciones) — directamente por API, sin navegador. Los números provienen de la API real, no los inventa el modelo. Dos compuertas de escritura evitan crear o contabilizar un documento por accidente en la contabilidad real. Auto-paginación, multi-cuenta, búsqueda en ruso. Para Claude Code, Cursor, Codex, Cowork y Claude Desktop.

Inicio rápido, sin instalación en el sistema:

uvx moysklad-mcp-ru

Clientes, token y la forma de «pídele a tu IA que lo instale»: en la sección «Instalación».

⚠️ alpha. Ayuda con la operativa contable, pero es una herramienta, no un sustituto del contable. El núcleo curado y el subconjunto de escritura están probados en un gabinete de pruebas; los métodos importados de la documentación son un mapa para explorar (las rutas son fiables, los cuerpos de las solicitudes de escritura verifícalos en la documentación o llámalos mediante ms_call_raw). Detalles en la sección «Advertencias».

Para qué sirve

La contabilidad vive en MoySklad, y el asistente de IA normalmente es inútil: o va por el navegador y tropieza, o inventa cifras que suenan convincentes. moysklad-mcp-ru le da al agente acceso directo a la JSON API 1.2 de tu cuenta:

• Números de la API real, no de la cabeza del modelo. Existencias, pedidos, beneficios, facturación: es la respuesta de MoySklad, con fuente y campos.
• Escritura tras dos compuertas. Crear un documento hace un BORRADOR; contabilizar (mueve la contabilidad) es un paso destructivo separado con confirmación. La escritura está desactivada por completo hasta que se active explícitamente y se dirija a un gabinete de pruebas.
• Sin navegador. Llamadas HTTPS directas con el token del gabinete.

Dile al agente en palabras normales: «muestra las existencias», «qué conviene re-pedir», «crea una recepción de 10 unidades de Hornos del proveedor» — elegirá el método o escenario.

Qué hay dentro

No es «una herramienta por endpoint», sino 8 meta-herramientas genéricas sobre el catálogo — cobertura completa de la API con una superficie pequeña.

ваш ИИ-агент
      │
      ▼
 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-herramientas (ms_search_methods, ms_describe_method, ms_call_method, ms_call_raw, ms_fetch_all, ms_map, + herramientas de gabinetes).

Herramientas de lectura 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. Los kopeks se convierten automáticamente a rublos.

Herramientas de escritura (tras dos compuertas):

Herramienta	Nivel	Función
ms_build_document	read	Vista previa de CUALQUIER tipo: resolución de enlaces + cuerpo exacto, SIN escritura.
ms_create_document	write	Crear CUALQUIER tipo de rol como BORRADOR (applicable:false).
ms_build_purchaseorder / ms_create_purchaseorder	read / write	Pedido tipado a proveedor (por compatibilidad).
ms_post_document	destructive	Contabilizar documento (applicable:true) — mueve la contabilidad.
ms_delete_document	destructive	Eliminar documento (limpieza).

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

Catálogo — basado en esquemas de la documentación oficial de MoySklad: 892 métodos (el núcleo curado está verificado en vivo; el resto se importó de la documentación). ms_call_raw obtiene todo lo que aún no está en el catálogo.

Qué se puede preguntar

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

¿No sabes por dónde empezar? Di «qué sabes hacer con mi gabinete» o llama a ms_map.

Modelo de seguridad

El token del gabinete mueve existencias y dinero. Cada método está clasificado:

• read → se ejecuta de inmediato;
• write (crear borrador) → requiere confirm_write=true Y la escritura activada MOYSKLAD_ALLOW_WRITE=1;
• destructive (contabilizar / eliminar) → además i_understand_this_modifies_data=true.

Dos capas independientes: (1) guard de proceso (MOYSKLAD_ALLOW_WRITE, por defecto DESACTIVADO, opcional pin al gabinete MOYSKLAD_WRITE_CABINETS) — protección contra dirigirlo a un gabinete de producción; (2) compuerta por llamada. El guard cubre también los ms_call_method/ ms_call_raw crudos, no solo las herramientas tipadas. 0 mutaciones marcadas como read — se verifica con una prueba (test_safety_catalog) en CI. La creación siempre hace un BORRADOR; la contabilización es un paso aparte.

Instalación

Guía detallada en QUICKSTART.md. Tres vías, un resultado:

1. Lo más fácil: pídele a tu IA (sin terminal). Abre Claude / Cowork y di: «instala MoySklad MCP» — el agente te guiará con el moysklad-mcp-install/ integrado.
2. Descargar y hacer clic. Toma el release-zip, descomprímelo, doble clic en install.command (macOS) / install.bat (Windows), pega el token.
3. Técnico. python3 install.py --client <твой-клиент> (claude-desktop / claude-code / codex / opencode).
4. Para desarrolladores. Paquete en PyPI — ejecución sin instalación: uvx moysklad-mcp-ru. Para Claude Desktop — bundle .mcpb listo desde el release (doble clic, el token se introduce en la ventana de ajustes). Lista completa de canales y cómo se recorta el release — en docs/DISTRIBUTION.md.

Para las vías 1–3 no necesitas ni pip install ni editar JSON: las dependencias se instalan solas en el primer arranque (venv local); de ti solo se necesita el token.

Dónde obtener el token: MoySklad → Ajustes → Usuarios → Tokens de acceso. El token se guarda en ~/.moysklad-mcp/cabinets.json (local, chmod 600, nunca en el repo ni en el chat). Soporte de multi-cuenta — varios gabinetes con cambio desde el chat (ms_add_cabinet / ms_use_cabinet).

Verificación tras la instalación. Instalado por paquete (uvx, pip): moysklad-mcp-ru doctor — imprime la versión, el número de herramientas, el tamaño del catálogo y el estado de la compuerta de escritura; no accede a la red. Trabajas desde el clon: python3 serve.py ms --selfcheck → «OK: ms ready, N tools».

Dinero

Todos los importes en la API están en kopeks. Las herramientas de lectura devuelven rublos. En la escritura, convert_money_to_kopecks convierte precios/importes de rublos a kopeks (price posiciones, sum, objetos price). Las meta-herramientas crudas trabajan en kopeks tal cual.

Probado en combate

• Host api.moysklad.ru/api/remap/1.2, listas en rows, offset+limit (máx. 1000).
• Límite: bucket 45/3s, ventana 3000 ms, el informe pesado de existencias pesa 5 unidades.
• Estricto: Accept: application/json;charset=utf-8 exacto (si no, 400 código 1062), Accept-Encoding: gzip (si no, 415).
• Escritura (gabinete demo): abanico create→read-back→contabilización→movimiento de existencias→ eliminación→reversión en los 6 tipos de rol + purchaseorder. Dinero ×100 correcto, supply/salesreturn +, demand/purchasereturn −, las facturas no mueven, la eliminación revierte, las devoluciones se crean standalone.

Advertencias (verifica con la documentación viva)

• Métodos importados de la documentación: las rutas son fiables, los cuerpos de escritura no. Trátalos como mapa de exploración: confírmalos en la documentación o llámalos mediante ms_call_raw. El núcleo curado y el subconjunto de escritura son fiables.
• El gabinete eclipsa el entorno: el gabinete activo en cabinets.json tiene prioridad sobre las variables de entorno. Un 401 inexplicable — revisa primero el almacén.
• Escritura solo en gabinete de pruebas. No dirijas MOYSKLAD_ALLOW_WRITE=1 a la contabilidad de producción hasta que lo verifiques tú mismo en pruebas.

Estructura

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

Licencia

MIT. El core/ de proveedor — bajo MIT de Ilya Utov, ver NOTICE. La arquitectura (catálogo basado en esquemas, compuerta de seguridad, errores unificados, auto-paginación) reutiliza las ideas más sólidas de marketplaces-mcp-ru.

¿Encontraste un fallo? Abre un issue. Esto es alpha y código abierto: instálalo, pruébalo con tus propios datos, experimenta.

---

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

---

Quién lo hizo

Ilya Utov, laboratorio AI Frontier. Cómo están construidas estas herramientas por dentro, lo escribo en Telegram y LinkedIn.

También están:

• humanizer-ru: elimina rastros de redes neuronales del texto en ruso
• marketplaces-mcp-ru: Wildberries, Ozon, Yandex Market y Avito directamente desde el agente
• small-business-ru: 34 habilidades para pequeñas empresas, calculan impuestos y verifican contrapartes por INN
• consilium-principis: consejo de pensadores, donde cada cita se verifica palabra por palabra
• hefest: seguridad química de fábrica, totalmente offline

Todos los proyectos en una lista, organizados por propósito: ilyautov.github.io. Código fuente: github.com/ilyautov. ¿Te resultó útil? Dale una estrella: así lo encuentran otros.