shopify-operations-mcp

Safe-write MCP server for Shopify Admin API operations

An agent can read and modify a Shopify store without being able to cause an unrecoverable accident. The safety layer is the differentiator: every write previews before it commits, large or irreversible changes require out-of-band human approval, and every action is recorded to a tamper-evident hash-chained audit file.

Architecture

flowchart TB

subgraph agent["Agent"] A[Claude] end

subgraph mcp["MCP stdio transport"] T[tools/call] end

subgraph core["safe-write-mcp-core"] PS[PlanStore] AS[ApprovalServer] end

subgraph shopify["Shopify Admin API"] GQL[GraphQL endpoint /admin/api/2026-04/graphql.json] end

subgraph audit["Audit"] LF[JSONL audit file hash-chained] end

A -->|"MCP stdio"| T T -->|create plan| PS T -->|preview| PS T -->|execute plan| PS PS -->|awaiting_approval| AS AS -->|approve/reject| PS PS -->|execute| GQL PS -->|record| LF

style PS fill:#e1f5fe style AS fill:#fff3e0 style LF fill:#f3e5f5 style GQL fill:#e8f5e9

The two-phase pattern (preview → token → execute) is the core discipline. Every write tool:

1. Preview — reads current state and computes what would change, performing zero mutation calls
2. Token — issues a plan token bound to the exact previewed manifest via a SHA-256 fingerprint
3. Approval — plans exceeding approvalRequiredAboveItems (default 25) or containing always-gated operations wait for human approval at the token-bearing URL the server prints on startup (e.g. http://127.0.0.1:4319/?token= )
4. Execute — re-reads current values, refuses if they drifted from the preview (STATE_CHANGED), then applies mutations per-item with a full success/failure ledger

A plan whose manifest exceeds hardMaxItems (default 250) is refused outright — no token, no approval path.

Irreversible operations (cancel_order, refund_order) always require approval regardless of item count and cannot be rolled back. Reversible operations (price changes, inventory adjustments) support rollback within a configurable window (default 24 hours).

Threat model

The risk is not a malicious agent — the agent is trusted to author correct GraphQL. The risk is a trusted-but-fallible agent: syntactically perfect, well-formed operations whose *scope* is the problem.

The killer scenario — a syntactically perfect bulk reprice with a misplaced decimal:

update_prices([...], newPrice: 1.5)   ← meant 15.00, typed 1.5

A 500-product bulk update that runs without preview-and-approve, or where the agent's price calculation contains a typo, produces exactly the wrong result at scale. Approval would catch it: a human sees "change 500 prices from $X to $1.50" and flags the不对劲. Without approval, or without the preview that makes the damage visible *before* it happens, the error lands silently in Shopify.

Three mechanisms carry the safety guarantee:

1. Preview-first, computed-diff. Every write tool reads current state and computes the manifest ({ref, before, after} pairs) without calling any mutation. A STATE_CHANGED re-read at execute time refuses the write if the world moved since preview. The blast radius is visible *before* anything changes.

2. Approval gating above the threshold. Plans touching >= approvalRequiredAboveItems items (default 25) require human approval. The threshold is sized for "is this large enough to warrant a human eye?" — meaningful for bulk value changes; irrelevant for one-item operations (which get unconditional approval for irreversible ops instead).

3. Plan token bound to exact manifest. The token is a SHA-256 fingerprint of the exact previewed manifest — not an opaque ID. Swapping in a wider set of items or a different price at execute time produces a different fingerprint and is refused as STATEMENT_MISMATCH.

Rollback provides recovery for reversible mistakes (wrong price, wrong inventory level) within the rollback window. It does *not* recover from the irreversible operations: a cancelled order stays cancelled, a refunded payment stays refunded.

Quick start

npm install

npm test npm run build

Set the required environment variable and point Claude Desktop at the server (see Configuration below). node dist/index.js starts the localhost approval UI alongside the MCP stdio server.

Demo: the step-by-step walkthrough script (store-wide reprice refused → approval-gated reprice → one-call rollback → hash-chained audit) is in docs/demo-runbook.md.

Configuration

Configuration file (default config.json in the working directory, or path via SHOPIFY_CONFIG):

{

"shopify": { "storeDomain": "my-store.myshopify.com", "apiVersion": "2026-04" }, "plans": { "planTtlMs": 60000, "approvalRequiredAboveItems": 25, "hardMaxItems": 250, "maxPriceChangePct": 30, "rollbackTtlMs": 86400000 }, "approvalServer": { "enabled": true, "port": 4319, "requireAuth": true }, "protectedTags": ["do-not-touch"], "callerId": "shopify-operations-mcp" }

Config reference

Invariant: plans.hardMaxItems must be >= plans.approvalRequiredAboveItems. The loader throws if violated.

Environment variables

All config fields are overridable by environment variables (precedence: env > config file > default). SHOPIFY_ADMIN_TOKEN is required and only ever read from the environment.

Tools

Read tools

search_products

Search products by title, SKU, vendor, or tag. Returns products with variants, current prices, and per-location inventory levels.

Arguments:

Returns: products[] with id, title, vendor, tags, variants (each with id, sku, price, inventoryItemId, inventoryLevels), plus flags.protected / flags.protectedTags indicating whether the product carries a protected tag.

Safety properties: Pure read — zero mutation calls. Protected-tagged products are returned (never filtered out) so a later write plan that touches them is refused.

list_orders

List orders filtered by financial status, fulfillment status, and date range.

Arguments:

Returns: orders[] with id, name, financialStatus, fulfillmentStatus, totalPrice, lineItems[].

Safety properties: Pure read — zero mutation calls.

Write tools (two-phase)

All write tools go through preview → token → (approval) → execute.

update_inventory

Set absolute inventory quantities at a named location for multiple inventory items. Preview reads current levels; execute calls inventorySetQuantities.

Arguments:

Safety properties:

• Threshold gating: requires approval when adjustments.length >= approvalRequiredAboveItems (default 25); refused outright when > hardMaxItems (default 250)
• Protected-tag enforcement: plans touching a product with a protected tag throw PROTECTED_RESOURCE before a token is issued — no approval path
• Per-item ledger: partial failure is recorded, never hidden
• Rollback: supported — restores before.available quantities via the snapshot

cancel_order

Cancel a Shopify order. Always requires approval regardless of item count. Cannot be rolled back.

Arguments:

Safety properties:

• Always approval: alwaysRequireApproval: true is hardcoded in the tool — approval thresholds are never consulted
• No snapshot: no snapshotStore.capture() call — rollback is not opened for this operation
• Rollback: refused with ROLLBACK_UNSUPPORTED — cancellation is a state transition, not a value change

refund_order

Refund a Shopify order. Always requires approval regardless of item count. Cannot be rolled back.

Arguments:

Each RefundLineItem: {lineItemId, quantity, restockType?} where restockType is "RETURN" \| "NO_RESTOCK" \| "CANCEL".

Safety properties:

• **A