MoySklad MCP (RU)

Add or update a cabinet (a named set of API credentials), from chat. ⚠️ This puts the key into the chat transcript — requires i_understand_key_goes_to_chat=true. The terminal-free safe alternative is the installer (install.py / double-click), where the key never enters chat. Args: credentials: dict with the required fields for this service ({fields}). For Ozon: {{"client_id": "...", "api_key": "..."}}; for WB: {{"token": "..."}}. name: optional label. If omitted, the cabinet is named after the real shop name fetched from the marketplace (falls back to "main"). i_understand_key_goes_to_chat: must be true to proceed. Saved to ~/.marketplace-mcp/cabinets.json (local, chmod 600), never echoed.

PREVIEW any role document: resolve names to refs and show the EXACT body ms_create_document would send (money already kopecks). READS only; no write. Args: doc_type: one of demand | supply | purchaseorder | invoiceout | invoicein | salesreturn | purchasereturn. agent: counterparty name — supplier for supply/invoicein/purchasereturn/ purchaseorder, customer for demand/invoiceout/salesreturn. organization: own legal entity; omit to auto-use the only one on the cabinet. store: warehouse name. supply/demand move stock, so a store is expected; optional for the others. positions: list of {"product": name, "quantity": n, "price": rubles, optional "discount" %, "vat" %}. moment/name/description: optional. moment is "YYYY-MM-DD HH:MM:SS". Returns {"ok": true, "doc_type", "body", "resolved", "summary"} or an error.

PREVIEW a purchase order: resolve names to refs and show the EXACT body ms_create_purchaseorder would send (money already kopecks). Performs READS to resolve names; sends NO write. Inspect the body/summary before creating. Args: agent: supplier counterparty name (поставщик) — required. organization: own legal entity; omit to auto-use the only one on the cabinet. store: warehouse name (optional). positions: list of {"product": name, "quantity": n, "price": rubles, optional "discount" %, "vat" %}. moment/name/description: optional fields. moment is "YYYY-MM-DD HH:MM:SS". Returns {"ok": true, "body", "resolved", "summary"} or an error envelope.

Execute one READ endpoint from the catalog by operation_id. Target API: https://dev.moysklad.ru/doc/api/remap/1.2/. Reads only: nothing here changes data, so it runs without confirmation. To change data use ms_write_method, to delete use ms_delete_method. Args: operation_id: id from the catalog (see ms_search_methods). path_values: values for {placeholders} in the path. query: query-string parameters. body: JSON request body (a few read endpoints take one). Returns JSON: {"ok": true, "status", "data"} or the error envelope.

Check whether the required credentials are present in the environment. Does NOT reveal secret values — only reports which variables are set. Returns JSON: {"ready": bool, "missing": [str], "required": [str]}.

Create ANY role document as a DRAFT (applicable=false — not posted, moves nothing). WRITE — requires confirm_write=true AND MOYSKLAD_ALLOW_WRITE=1. Posting is a separate destructive step (ms_post_document). One body shape fits every order-like document (live-verified 2026-06-26 on all 6 types). Args: doc_type: one of demand | supply | purchaseorder | invoiceout | invoicein | salesreturn | purchasereturn. agent / organization / store / positions / moment / name / description: same as ms_build_document. confirm_write: required (write gate). Returns the created document envelope {"ok": true, "data": {... "id" ...}}, or the guard/gate/validation error (nothing sent).

Create a purchase order as a DRAFT (applicable=false — not posted, moves nothing). WRITE — requires confirm_write=true. Posting is separate (ms_post_document). Writes also require MOYSKLAD_ALLOW_WRITE=1 (off by default). Args: same as ms_build_purchaseorder, plus confirm_write. Returns the created document envelope {"ok": true, "data": {... "id" ...}}, or the guard/gate error (nothing sent).

DELETE a document — e.g. remove a test draft to clean up. DESTRUCTIVE — requires both confirmations. Args: doc_type: one of demand|supply|purchaseorder|invoiceout|invoicein| salesreturn|purchasereturn. doc_id: document id. Returns {"ok": true, "status": 200} on success, or the guard/gate error.

Execute one DESTRUCTIVE endpoint: deletes or irreversibly changes data. Target API: https://dev.moysklad.ru/doc/api/remap/1.2/. Both confirm_write=true and i_understand_this_modifies_data=true are required; nothing is sent without both. Args: operation_id: id from the catalog (see ms_search_methods). path_values: values for {placeholders} in the path. query: query-string parameters. body: JSON request body. confirm_write: must be true. i_understand_this_modifies_data: must be true. Returns JSON: {"ok": true, "status", "data"} or the error envelope.

Delete data at ANY path, including paths not in the catalog. Target API: https://dev.moysklad.ru/doc/api/remap/1.2/. DELETE only. Both confirm_write=true and i_understand_this_modifies_data=true are required. Args: path: full path beginning with '/'. method: DELETE. host: host override; defaults to the service's default host. query: query-string parameters. body: JSON request body. confirm_write: must be true. i_understand_this_modifies_data: must be true. Returns JSON: {"ok": true, "status", "data"} or the error envelope.

Return the full catalog record for one endpoint: method, host, path, scope, safety level, pagination style, rate limit, params and doc URL.

Auto-paginate a read endpoint and return every row in one response. Handles offset, last_id, cursor (Ozon v4/v5), page and WB lastChangeDate styles. The array path is taken from the catalog automatically. Args: operation_id: a read endpoint from the catalog. query / body / path_values: base parameters (cursor fields are managed). items_path: override the array path (default: the endpoint's own). limit: page size to request. max_items: hard cap to protect context (default 10000). Returns JSON: {"ok", "items", "total_fetched", "pages_fetched", "truncated"}.

Counterparties (customers and suppliers). Balance fields in kopecks. Args: limit/offset: pagination. filter: MoySklad filter (e.g. "name~ООО"). rubles: convert kopeck balance fields to rubles (default true). Returns JSON: {"ok": true, "data": {"meta", "rows": [ counterparties ]}}.

List a role document by type. Document total in "sum" (kopecks). Args: doc_type: one of demand | supply | purchaseorder | invoiceout | invoicein | salesreturn | purchasereturn. limit/offset: pagination. filter: MoySklad filter (e.g. "moment>=2026-06-01 00:00:00"). rubles: convert "sum" and money fields to rubles (default true). Returns JSON: {"ok": true, "data": {"meta", "rows": [ documents ]}}.

Cash balances by account/cashbox (kopecks). For cashflow over time use ms_call_method('ms_get_report_money_plotseries', ...) from the map. Args: rubles: convert kopeck balances to rubles (default true). Returns JSON: {"ok": true, "data": {"meta", "rows": [ {account, balance, ...} ]}}.

List customer orders. Document total is "sum" (kopecks in raw API). Args: limit: page size, max 1000. offset: pagination offset. filter: optional MoySklad filter (e.g. "moment>=2026-06-01 00:00:00"). rubles: convert "sum" and money fields to rubles (default true). Returns JSON: {"ok": true, "data": {"meta", "rows": [ orders ]}}.

List products/services/bundles (assortment) with prices and stock. Args: limit: page size, max 1000. offset: pagination offset. filter: optional MoySklad filter expression (e.g. "archived=false"). rubles: convert kopeck money fields to rubles (default true). Returns JSON: {"ok": true, "data": {"meta", "rows": [ products ]}}. Sale prices and buy price are kopecks in the raw API; rubles=true converts them.

Profitability by product (sale, cost, profit, margin). Money in kopecks. Args: moment_from / moment_to: period bounds "YYYY-MM-DD HH:MM:SS" (report needs them). limit/offset: pagination (rows under "rows"). rubles: kopecks→rubles (default true). Returns JSON: {"ok": true, "data": {"meta", "rows": [ ... ]}}.

Read ANY endpoint by path, including ones missing from the catalog. Target API: https://dev.moysklad.ru/doc/api/remap/1.2/. Safe verbs only (GET, HEAD, OPTIONS). To change data use ms_write_raw, to delete use ms_delete_raw. Args: path: full path beginning with '/', e.g. "/api/remap/1.2/async". method: safe verb, GET by default. host: host override; defaults to the service's default host. query: query-string parameters. body: JSON request body (rare on reads; some APIs want one). Returns JSON: {"ok": true, "status", "data"} or the error envelope.

List all endpoints in one section. Args: section: section name (see ms_list_sections), e.g. "statistics". Returns JSON list of {operation_id, method, path, safety, summary}.

Current stock snapshot, grouped by product (fast /report/stock/all/current). Args: stock_type: quantity | freeStock | reserve | inTransit | stock. Default quantity. include_zero: include zero-stock lines (adds include=zeroLines). Returns JSON: {"ok": true, "data": [ {assortmentId, <stock_type>}, ... ]}. No money in this report, so values are returned as-is (quantities).

Warehouses/stores (small dictionary). No money fields. Returns JSON: {"ok": true, "data": {"meta", "rows": [ {name, id, ...} ]}}.

Turnover by product: opening/income/outcome/closing in qty and money (kopecks). Args: moment_from / moment_to: period bounds "YYYY-MM-DD HH:MM:SS" (required by the report). limit/offset: pagination. rubles: kopecks→rubles (default true). Returns JSON: {"ok": true, "data": {"meta", "rows": [ ... ]}}.

Return the full plan for one workflow: ordered steps (each naming a catalog operation_id and why), interpretation guidance, and common mistakes to avoid. Args: name: workflow name (see {svc}_list_workflows).

List configured cabinets for this marketplace and which one is active. Returns JSON: {"active": str|null, "cabinets": [names], "fields_needed": [...]}. Secret values are never returned.

List API sections and how many catalog endpoints each contains.

List ready-made analytical workflows (recipes) for this marketplace. Returns JSON: [{name, category, when_to_use}]. Use {svc}_get_workflow to fetch the full step-by-step plan for one.

The big picture: business entities this API covers and the go-to methods for each. Call with no args to see the whole map ("you are here"); pass entity="reviews" (or stocks/prices/orders/…) to list every method of one entity. Use this before guessing — it orients you fast.

Live connectivity + auth check: GET assortment?limit=1. Returns {"ok": true, "status": 200, "data": {...}} when the token works, or the canonical error envelope (auth/forbidden/network/...) otherwise. Use this on the cabinet to confirm the token before anything else.

POST / провести a document: sets applicable=true, which MOVES STOCK AND MONEY in the books. DESTRUCTIVE — requires confirm_write=true AND i_understand_this_modifies_data=true. Separate from creation on purpose. Args: doc_type: one of demand|supply|purchaseorder|invoiceout|invoicein| salesreturn|purchasereturn. doc_id: document id (the "id" field returned by create). Returns the updated document envelope, or the guard/gate error (nothing sent).

Delete a stored cabinet. If it was active, another becomes active. Args: name: the cabinet to remove.

Search the endpoint catalog by keyword (works in Russian and English). Args: query: free text, e.g. "остатки", "stocks", "update price". limit: max results (1-50). Returns JSON list of matching endpoints (best first).

Change / rotate the API key from chat (e.g. the old one expired or leaked). ⚠️ The key goes into the chat transcript — requires i_understand_key_goes_to_chat=true. The safe, terminal-free alternative is the installer, where the key never enters chat. Use a scoped key and rotate it in the seller cabinet if it was exposed. Args: credentials: dict with the required fields ({fields}). cabinet: which cabinet to update. Default: the active one (so "my key expired" just works). If there is none, the cabinet is named from the marketplace's shop name, else "main". i_understand_key_goes_to_chat: must be true to proceed. On success the key is validated against the marketplace and the shop name is reported. Saved locally (chmod 600), never echoed back.

Switch the active cabinet. Subsequent API calls use its credentials. Args: name: the cabinet to activate (see ms_list_cabinets).

Execute one WRITE endpoint from the catalog: create or update data. Target API: https://dev.moysklad.ru/doc/api/remap/1.2/. Requires confirm_write=true; nothing is sent without it. Irreversible operations live in ms_delete_method, reads in ms_call_method. Args: operation_id: id from the catalog (see ms_search_methods). path_values: values for {placeholders} in the path. query: query-string parameters. body: JSON request body. confirm_write: must be true. Returns JSON: {"ok": true, "status", "data"} or the error envelope.

Create or update data at ANY path, including paths not in the catalog. Target API: https://dev.moysklad.ru/doc/api/remap/1.2/. POST, PUT and PATCH only; requires confirm_write=true. Args: method: POST, PUT or PATCH. path: full path beginning with '/'. host: host override; defaults to the service's default host. query: query-string parameters. body: JSON request body. confirm_write: must be true. Returns JSON: {"ok": true, "status", "data"} or the error envelope.