moysklad-mcp-ru

# Tool List > 🇬🇧 [English version](README.en.md) **Direct AI access to MySklad for Claude Code, Cursor, Codex, and Cowork**     > ⚠️ **alpha.** Helps with accounting operations, but this is a tool, not a replacement for an accountant. Curated core and write section are verified by testing on a test cabinet; imported methods from documentation are a map for exploration (paths are reliable, write request bodies should be verified by documentation or called via `ms_call_raw`). Details are in the "Notes" section. ## Why is this needed? Accounting lives in MySklad, but AI assistants are usually useless: either they go through the browser and stumble, or they make up numbers that sound confident. `moysklad-mcp-ru` gives the agent **direct access to JSON API 1.2** of your account: - **Numbers from real API, not from model imagination.** Balances, orders, profit, turnover - this is a response from MySklad, with source and fields. - **Recording with two gates.** Creating a document makes a DRAFT; conducting (moves accounting) is a separate destructive step with confirmation. Recording is generally disabled until it's explicitly enabled and directed to a test cabinet. - **No browser.** Direct HTTPS calls by cabinet token. Tell the agent in simple words: "show balances", "what needs to be reordered", "create a receipt for 10 Rog from supplier" - it will select a method or scenario. ## What's inside **Not "one tool per endpoint", but 8 generic meta-tools over catalog** - full API coverage with a small surface. ``` your AI agent │ ▼ 8 meta-tools ──► catalog (endpoints.yaml) ──► common core search / describe / client · safety · errors call / call_raw / pagination · registry fetch_all / map / ... │ + typed tools (ms_get_stock, ms_create_document, …) ▼ MySklad JSON API 1.2 (HTTPS) ``` **Meta-tools** (`ms_search_methods`, `ms_describe_method`, `ms_call_method`, `ms_call_raw`, `ms_fetch_all`, `ms_map`, + cabinet tools). **Typed read-tools:** `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 types), `ms_ping`. Kopecks are automatically converted to rubles. **Write tools (with two gates):** | Tool | Level | Purpose | |---|---|---| | `ms_build_document` | read | Preview ANY type: resolve links + exact body, WITHOUT recording. | | `ms_create_document` | write | Create ANY role type as DRAFT (`applicable:false`). | | `ms_build_purchaseorder` / `ms_create_purchaseorder` | read / write | Typed purchase order from supplier (for compatibility). | | `ms_post_document` | destructive | Conduct document (`applicable:true`) - moves accounting. | | `ms_delete_document` | destructive | Delete document (cleanup). | 7 role types: `purchaseorder`, `supply`, `demand`, `invoicein`, `invoiceout`, `salesreturn`, `purchasereturn`. **Catalog - schema-driven from official MySklad documentation:** 892 methods (curated core is verified live; the rest is imported from documentation). `ms_call_raw` retrieves everything that's not yet in the catalog. ## What can be asked ``` show balances and what needs to be reordered pull profit by products for last month who owes us money create draft receipt: 10 "Rog" from "LLC Supplier" for 250 ₽ (on test cabinet) conduct this receipt and show how the balance changed ``` Not sure where to start - say **"what can you do with my cabinet"** or call `ms_map`. ## Safety model Cabinet token moves balances and money. Each method is classified: - **read** → executed immediately; - **write** (create draft) → requires `confirm_write=true` **AND** enabled recording `MOYSKLAD_ALLOW_WRITE=1`; - **destructive** (conduct / delete) → also requires `i_understand_this_modifies_data=true`. **Two independent layers:** (1) process guard (`MOYSKLAD_ALLOW_WRITE`, disabled by default, optional pin to cabinet `MOYSKLAD_WRITE_CABINETS`) - protection against directing to a combat cabinet; (2) per-call gate. Guard covers raw `ms_call_method` / `ms_call_raw`, not just typed tools. **0 mutations marked as read** - verified by test (`test_safety_catalog`) in CI. Creation always makes DRAFT; conducting is a separate step. ## Installation Detailed guide in **[QUICKSTART.md](QUICKSTART.md)**. Three ways, one result: 1. **Easiest - ask your AI (without terminal).** Open Claude / Cowork and say: *"install MySklad MCP"* - the agent will guide you through the built-in `install-skill/`. 2. **Download and click.** Take release-zip, unpack, double click `install.command` (macOS) / `install.bat` (Windows), insert token. 3. **Technical.** `python3 install.py --client <your-client>` (claude-desktop / claude-code / codex / opencode). 4. **For developers.** Package on PyPI - launch without installation: `uvx moysklad-mcp-ru`. For Claude Desktop - ready `.mcpb`-bundle from [release](https://github.com/ilyautov/moysklad-mcp-ru/releases) (double click, token entered in settings window). Full list of channels and how the release is cut - in **[docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)**. For paths 1-3, no `pip install` or JSON edits are needed: dependencies are installed automatically during the first launch (local venv), all you need is the token. **Where to get token:** MySklad → Settings → Users → Access tokens. Token is stored in `~/.moysklad-mcp/cabinets.json` (locally, chmod 600, never in repo or chat). Support for **multi-cabinet** - several accounts with switching from chat (`ms_add_cabinet` / `ms_use_cabinet`). **Verification after installation:** `python3 serve.py ms --selfcheck` → «OK: ms ready, N tools». ## Money All amounts in API are in kopecks. Read-tools return rubles. When recording `convert_money_to_kopecks` converts prices / amounts rubles→kopecks (`price` position, `sum`, price-objects). Raw meta-tools work in kopecks as is. ## Verified by combat - Host `api.moysklad.ru/api/remap/1.2`, lists in `rows`, offset+limit (max 1000). - Limit: bucket **45/3s**, window 3000 ms, heavy report of balances weighs 5 units. - Strictly: `Accept: application/json;charset=utf-8` exactly (otherwise 400 code 1062), `Accept-Encoding: gzip` (otherwise 415). - **Recording (demo cabinet):** create→read-back→conducting→balance movement→deletion→rollback on all 6 role types + purchaseorder. Money ×100 are correct, supply/salesreturn +, demand/purchasereturn −, invoices do not move, deletion rolls back, returns are created standalone. ## Notes (verify with live documentation) - **Imported methods from documentation: paths are reliable, write bodies are not.** Consider them as an exploration map: verify by documentation or call via `ms_call_raw`. Curated core and write section are reliable. - **Cabinet overrides env:** active cabinet in `cabinets.json` has priority over environment variables. Unexplained 401 - first check the store. - **Recording only on test cabinet.** Do not direct `MOYSKLAD_ALLOW_WRITE=1` to combat accounting until you check on test. ## Structure ``` core/ ← vendor engine ilyautov/marketplaces-mcp-ru (MIT, unchanged) moysklad_mcp/ ← MySklad specifics: server.py, build.py, money.py, refs.py, write_guard.py, endpoints.yaml(+curated), workflows.yaml, entities.yaml tests/ ← 70 offline tests scripts/ ← ingest_moysklad.py (documentation parser), package_release.py serve.py ← launcher (auto-venv): python3 serve.py ms [--selfcheck] install.py + .command/.bat/.sh + install-skill/ ← installation for 4 clients .mcp.json + .claude-plugin/ .codex-plugin/ .cursor-plugin/ ← plugin manifests docs/ ← research, audit, RUNBOOKs, recovery points (dev-docs) ``` ## License MIT. Vendor `core/` - under MIT Ilya Utov, see [`NOTICE`](NOTICE). Architecture (schema-driven catalog, safety gate, unified errors, auto-pagination) reuses strongest ideas [marketplaces-mcp-ru](https://github.com/ilyautov/marketplaces-mcp-ru). Found a bug - create an issue. This is alpha and open code: install, test on your data, experiment.