shopify-operations-mcp server

by jpka·io.github.jpka/shopify-operations-mcp·v0.1.2

No reviews yet

Safe-write Shopify operations: plan-before-execute writes with out-of-band approval and audit.

B78/100grade B

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

B78/100

full report

Adoption

New

0 stars49 downloads/wk

Reviews

Write one

Nobody has reviewed shopify-operations-mcp yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

shopify-operations-mcp tools (9, 6 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

cancel_orderwrite action
Preview and execute order cancellation (two-phase). Cancellation is permanent — an order cannot be uncancelled — so every cancel plan ALWAYS requires human approval through the localhost approval UI, regardless of item count, and cancel_order can never be rolled back. The preview is a zero-write call that returns the refund implication and flags the human sees before granting or denying; execute a
create_discountwrite action
Preview and execute the creation of a discount code (two-phase). Previews the planned discount (pure reads, zero mutation) and returns a plan_token; nothing changes until execute_plan runs with that token. A plan touching at least plans.approvalRequiredAboveItems items requires human approval through the localhost approval UI before it executes. Discount creation is reversible via rollback_plan, w
execute_planwrite action
Execute a previously previewed write (update_prices, update_inventory, create_discount, refund_order, or cancel_order). Pass back the exact plan_token and the exact manifest from the preview response. The token is single-use, expires, and refuses any manifest that does not fingerprint-match the preview; write plans also refuse when the current data drifted since the preview (STATE_CHANGED). Plans
list_orders
List cancellable and refundable orders (id, name, financial and fulfillment status, total price, line items), optionally filtered by financial status, fulfillment status, and created-date range. Read-only: a single GraphQL query over the orders connection with no mutation.
refund_orderwrite action
Preview and execute an order refund (two-phase). Previews via Shopify's refundCalculate (zero writes) to obtain exact suggested refund amounts, then — only after a human approves through the localhost approval UI — executes via refundCreate. ALWAYS requires human approval regardless of item count, because a refund is irreversible and unwinds a payment. Refunds cannot be rolled back (refund_order i
rollback_plan
Undo a previously executed reversible plan (update_prices, update_inventory, or create_discount) in one call: restores each item to its previewed before-state by re-applying inverse mutations. Requires no approval — restoring prior state is the safe direction. Refused with ROLLBACK_UNSUPPORTED for non-reversible kinds (cancel_order, refund_order) or unknown tokens, and ROLLBACK_WINDOW_EXPIRED once
search_products
Search products by title, sku, vendor, or tag and return variant pricing and per-location inventory references. Read-only: composes a Shopify search string, walks the cursor-paginated products connection to completion, and flags any product carrying a configured protected tag so a later write plan touching it is refused at preview time.
update_inventorywrite action
Preview and execute bulk inventory quantity changes at one location (two-phase). Sets the available quantity of each inventory item at the location to the absolute value supplied (not a delta). Previews planned changes (pure reads, zero mutation) and returns a plan_token; nothing changes until execute_plan runs with that token. A plan touching at least plans.approvalRequiredAboveItems items requir
update_priceswrite action
Preview and execute bulk variant price changes (two-phase). Previews the exact price change for every matched variant (pure reads, zero mutation) and returns a plan_token; nothing changes until execute_plan runs with that token. A plan that changes any single variant's price by more than plans.maxPriceChangePct (default 30%), or that touches at least plans.approvalRequiredAboveItems variants, requ

Public scan report

scanner v0.1.10 · 2026-11-03 · same rubric, same numbers if you re-run it

no findings

Code scan42 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitystatic API keys via environment variables6/15
Maintenancelast push 60 days ago12/15
Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Overall 78/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

How shopify-operations-mcp compares

Against every graded E-commerce MCP server, from our own scans and uptime checks. Updated after each scan run.

Safety score: 78/100; higher than 67% of 2,174 E-commerce servers
Tools: 9; the typical E-commerce server has 6
Tools that change things: 67%; typical: 0%. Fewer write tools means less an agent can break
Downloads a week: 49; more than 45% of 411 E-commerce servers with a package

What its tools let an agent do: 3 read · 1 create · 3 change · 1 delete · 1 run or deploy

Install shopify-operations-mcp in Claude Code, Cursor or VS Code

Runs npx -y shopify-operations-mcp on your machine. Read the scan report first; the gateway never runs local packages.

claude mcp add shopify-operations-mcp -- npx -y shopify-operations-mcp

Add to Cursor

What the publisher says

From the shopify-operations-mcp repository's README, as published. We do not edit it. Read it on GitHub

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<br/>/admin/api/2026-04/graphql.json]
    end

    subgraph audit["Audit"]
        LF[JSONL audit file<br/>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:

Preview — reads current state and computes what would change, performing zero mutation calls
Token — issues a plan token bound to the exact previewed manifest via a SHA-256 fingerprint
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=)
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 (cancelorder, refundorder) 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 STATECHANGED 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.

Shortened. The full README is on GitHub.

Nothing above is checked by us. What we check is on the safety report.

shopify-operations-mcp: common questions

Is shopify-operations-mcp server safe?: Mostly: it is graded B (78/100). Read the shopify-operations-mcp safety report
How do I install shopify-operations-mcp?: It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
Does shopify-operations-mcp need an API key?: Yes. The registry entry asks for SHOPIFY_ADMIN_TOKEN.
Is shopify-operations-mcp maintained?: The last commit was 61 days ago (2026-09-04). The latest release is v0.1.2.
What can I use instead of shopify-operations-mcp?: Servers from other publishers that do the same job: Shopware MCP server, HasData Shopify MCP server and Markifact - Ads & Analytics MCP server.
How does shopify-operations-mcp compare with other E-commerce MCP servers?: safety score 78/100 (higher than 67% of 2,174 E-commerce servers); tools 9 (the typical E-commerce server has 6); tools that change things 67% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.

Alternatives to shopify-operations-mcp

Same job from other publishers: the closest match first, then the best rated.

Shopware
Query and safely manage a Shopware 6 shop: products, orders, customers, stock, audits, reports.
not reviewed
Growing
B
HasData Shopify
The public product catalogue and collections of any Shopify storefront, as structured JSON.
not reviewed
Growing
A
Markifact - Ads & Analytics
AI marketing agent for Google Ads, Meta, GA4, TikTok, LinkedIn, Shopify, HubSpot and more.
not reviewed
Growing
A
AsoBeast
App Store and Google Play ASO: keyword rankings, competitors, reviews, audits and an action queue.
not reviewed
Growing
A
Shopify
MCP server for Shopify — Admin REST API (orders, products, customers, inventory, fulfillments)
More from codespar →
not reviewed
Growing
B

Run it through the gateway

Local package. It runs on your machine, not through the gateway.

Rating: —
Safety grade: B · 78/100
Stars: 0
Downloads/wk: 49
Price: Free
Licence: MIT
Transport: Local · npm
Version: 0.1.2
Category: E-commerce
Last release: 2026-09-04

Credentials it needs

SHOPIFY_STORE_DOMAINThe myshopify.com store domain, e.g. my-store.myshopify.com. Overrides shopify.storeDomain from the config file.
SHOPIFY_ADMIN_TOKENsecretShopify Admin API access token. Required and only ever read from the environment — never from the config file.
SHOPIFY_CONFIGPath to a config.json with shopify/plans/approvalServer/protectedTags settings. Defaults to ./config.json in the working directory.
SHOPIFY_PLAN_TTL_MSHow long a plan token stays valid before it must be executed or expires, in milliseconds. Default 60000.
SHOPIFY_APPROVAL_SERVER_PORTPort the localhost human-approval HTTP server binds to (127.0.0.1 only). Default 4319.
SHOPIFY_PROTECTED_TAGSComma-separated tags that plans may never modify; any plan touching an item carrying one is refused. Default do-not-touch.
SHOPIFY_CALLER_IDIdentity recorded as the caller on every audit log row. Default unknown.
SHOPIFY_AUDIT_PATHFile path for the tamper-evident JSONL audit log. Default shopify-operations-audit.jsonl in the working directory.

Own this server?

Claim it to keep the listing current and reply to reviews. Claiming never changes the grade or hides a review.

Claim listing

Badge for your README

Shows the safety grade and links back to this page. It updates itself after every scan and review.

[![mcp.market](https://mcp.market/badge/jpka-shopify-operations-mcp.svg)](https://mcp.market/server/jpka-shopify-operations-mcp)

How the badge works