Goal: the user said "install MoySklad MCP" — and within a few minutes tools for working with accounting (stock, products, orders, documents, reports, document posting) appeared in their AI client, without manually editing JSON and without pip install. Dependencies are installed by serve.py itself on first launch (local venv).
Repository: https://github.com/ilyautov/moysklad-mcp-ru — clone it or use the connected project folder (see Step 1).
What's inside: one MCP server ms (MoySklad JSON API 1.2). The token is stored locally in ~/.moysklad-mcp/cabinets.json (chmod 600, a separate MoySklad store, does not conflict with WB/Ozon), NOT in the client config and NOT in the repository.
Step 0 — DETERMINE THE ENVIRONMENT (critical, do not skip)
The environment determines what you can do yourself and what you can only guide the user through by hand. Be honest about the boundary: do NOT promise what the environment physically cannot do.
You are in Claude Code (or another local CLI where bash = the real machine)
bash runs ON the user's machine — you can do EVERYTHING yourself: get the code, run python3 install.py --client claude-code, help save the token, check serve.py ms --selfcheck.
Check: pwd && uname -a && whoami. The home folder is on their OS (not a container) → you are local, proceed through steps 1→4 yourself.
You are in Cowork (bash = an isolated Linux sandbox)
CRITICAL. Your bash is a separate Linux container. It does NOT see the Claude Desktop config, CANNOT register a host MCP, CANNOT run serve.py on the user's machine, and typing into their terminal is forbidden. Sign: uname -a shows a Linux container, home folder like /home/... or /sessions/....
In Cowork you do NOT install MCP yourself. Options (by preference):
- Via Claude Code, if available — prepare the commands from Steps 1-4 and ask them to run them there.
- Double-click + computer-use. The project files are already in the connected folder. Via computer-use (if you have access): open the folder in Finder/Explorer, double-click
install.command(macOS) /install.bat(Windows) /bash install.sh(Linux). The installer will open in the user's terminal and will ask for the token itself. - Walk through the steps in words — a short checklist, one step at a time, without a wall of text.
Don't write "I'll install it now" and don't pretend the server has appeared. Say directly: "I'm in a sandbox and can't configure MCP on your machine directly — let's do it via double-click / Claude Code."
Step 1 — Get the code onto the machine
Local folder: the connected project folder (a common case is that it already exists), or ~/moysklad-mcp. Check that it contains install.py и serve.py.
Check Python (3.10+ required): python3 --version (Windows: py -3 --version). No Python — see Troubleshooting, install it first.
Step 2 — Run the installation for the required client
install.py breaks nothing: it finds the config for the OS, appends the server entry WITHOUT the secret, and backs up the old config. Re-running is safe. It also copies the application to a stable folder ~/.moysklad-mcp/app, so that MCP doesn't break if the source folder is moved.
Ask the client. Commands (from the project folder):
| Client | Command | What it does |
|---|---|---|
| Claude Desktop (default) | python3 install.py --client claude-desktop |
Writes claude_desktop_config.json, backs up the old one |
| Claude Code (CLI) | python3 install.py --client claude-code |
PRINTS claude mcp add moysklad -- … ms — it must be executed |
| Codex (CLI) | python3 install.py --client codex |
PRINTS codex mcp add … — execute it |
| OpenCode | python3 install.py --client opencode |
Writes ~/.config/opencode/opencode.json |
For claude-code/codex install.py does NOT write the config itself — it prints the command, and it must actually be executed. Just to view the block: python3 install.py --print.
After installation (Claude Desktop / OpenCode) — restart the client. The first launch serve.py will create the venv itself and install the dependencies (a few seconds, output to stderr).
Step 3 — Token (where to get it and how to save it)
The token is NEVER placed in the repository or in the client config — it goes into ~/.moysklad-mcp/cabinets.json (chmod 600).
Where to get it: MoySklad → Settings → Users → Access tokens → create a Bearer token.
How to save it:
- Interactively:
python3 install.py(will ask for the token, Enter = skip). - With the flag (do not echo the real value into the chat):
python3 install.py --token <TOKEN>(multiple accounts —--cabinet account2). - From the chat, when the server is connected:
ms_add_cabinet(credentials={"token":"…"}), switchingms_use_cabinet, listms_list_cabinets.
Document writing (optional). Writing is OFF by default. For the agent to be able to create/post/delete documents (receipts, shipments, orders, invoices, returns), you need to set MOYSKLAD_ALLOW_WRITE=1 in the server environment — and point it ONLY to a TEST account, not to production accounting. Without the flag, all write tools safely refuse.
Security: do not print the token back into the chat even partially; if it leaked, reissue it in MoySklad (revoke the old one).
Step 4 — Verification
Self-check (token not needed): python3 serve.py ms --selfcheck → “OK: ms ready, N tools”.
From the chat after restart: ms_check_auth (will show the active account, what is missing; does not echo the secret) → then ms_ping (HTTP 200) → first live call ms_get_products or ms_get_stock. Real data came back — the installation succeeded.
Troubleshooting
command not found: python3: install Python 3.10+ from https://python.org. On Windows — check “Add python.exe to PATH”, open a new terminal. Double-clicking install.bat/install.command will tell you if Python is not found.
A malformed/empty account shadows env: the active account in cabinets.json takes priority over environment variables. An inexplicable 401 / “token malformed” — check the store: if the active account is empty/dummy, re-save the real token (install.py or ms_add_cabinet), or delete the malformed one (ms_remove_cabinet) and switch (ms_use_cabinet).
Tools did not appear: restart the client (the config is read at startup). For Claude Code/Codex, check that you actually EXECUTED the printed * mcp add commands. The first launch installs the venv — if it failed, run python3 serve.py ms --selfcheck manually and read stderr.
Writing returns “forbidden / writing disabled”: this is normal — set MOYSKLAD_ALLOW_WRITE=1 in the server environment and point it only to a test account. For posting/deleting, the tool additionally requires confirmation flags.
Memo (anti-overpromise)
- Claude Code / local CLI → you do everything yourself, up to and including verification.
- Cowork → you do NOT install MCP yourself. Double click (computer-use) OR Claude Code OR a step-by-step checklist. Honestly state the sandbox boundary.