shopify-store-sync-mcp
A read-only-by-default MCP server (plus CLI) that diffs and syncs configuration between Shopify stores, with plans, guardrails and never any deletes.
Discover setup —
list_storesshows configured store aliases, write permissions and protection;list_resource_typesshows what can be synced and how items are keyed.Inspect one store —
snapshot_storereads a store (or adir:snapshot folder) in portable form with store IDs replaced by handles;export_snapshotwrites it to JSON files for git (config as code).Compare two stores —
diff_storesreports field-by-field differences (only-in-source, changed, only-in-target, identical) with before/after values, or as a Markdown report;compare_itemdoes a single item side by side and checks whether its references exist in the target.Plan before writing —
plan_syncbuilds a dry-run plan with creates, updates, conflicts, missing references and files to upload, returning aplan_idthat expires in an hour;get_planshows it again or lists recent plans.Apply safely —
apply_planwrites only if the store hasallowWrites, re-reads the target to skip drifted items, uploads missing files, needs a human confirmation on protected stores, and never deletes;apply_statusfollows background applies andcancel_applystops one.Audit —
get_audit_logreads the local JSONL log of every write, filtered by plan, outcome or resource type.Theme settings —
diff_themescompares templates and settings between two stores' themes, read-only, with globs to ignore intentional differences.What it covers — metafield and metaobject definitions and entries, pages, menus, redirects, collections, shop policies, opt-in products (variants, prices, stock), metafield values, translations, and compare-only discounts; applied with cross-store ID remapping by handle and two-pass writes for interdependent items.
Also usable without an AI client — the same engine runs as a CLI with
--json,--format mdand--exit-codefor scheduled drift checks.
Enables comparison and synchronization of Shopify store configurations between multiple Shopify stores, including metafield and metaobject definitions, metaobject entries, pages, navigation menus, and URL redirects. Provides field-level diffs, dry-run sync plans, cross-store ID remapping by handle, drift protection, and guarded write operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shopify-store-sync-mcp diff my dev store against production and show me the changes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
https://github.com/user-attachments/assets/07dd060d-aec6-4b71-b29b-486bfd9ccf35
Compare, plan, confirm, apply: the full walkthrough, with sound. Every output shown is real, from two sample stores.
Real output of the server's tools on two sample stores.
What it syncs
The store setup that usually gets rebuilt by hand, plus the images it uses. References between items (a size guide pointing at a product, a menu linking to a page) are carried across by handle, so they land on the right item instead of a broken ID.
Resource | Keyed by | Notes |
|
| Name, description, pinning, storefront and customer account access, capabilities, validations. A type change is reported as a conflict, since Shopify can't change a definition's type in place. |
|
| Schema, access, capabilities. Fields are added or updated, never removed. Self-referencing definitions are handled. |
|
| Title, body HTML, template, published state. With |
|
| All field values, publish status. References to products, collections, pages and other metaobjects are remapped. A field the source leaves empty is never cleared in the target. With |
|
| Full item tree (3 levels), including customer account menus. Links to resources are remapped; custom URLs are kept; links to things that can't be matched are left out and reported. Links that only the target menu has are kept, in place, and the plan names them. |
|
| Thousands are fine. |
|
| Title, description, sort order, template, SEO and smart-collection rules (rules on a metafield definition are remapped). Manual collections keep their own product list. A new collection is not published to any sales channel. Manual versus smart is reported as a conflict. |
|
| Refund, privacy, terms, shipping and contact policy text. |
|
| Title, description, vendor, type, category, tags, template, SEO, options, images, and variants matched by option values: SKU, barcode, weight, taxable flag, inventory policy, inventory tracking, shipping, customs details (HS code, country of origin) and the variant's image. New products are created as drafts. Prices only with |
|
| Metafield values on products, collections, product variants and the shop. A value lands on the item with the same handle in the target; a variant value on the variant with the same option values; a shop value on the target's own shop. Reference values (including references to variants) are remapped. Filter with |
|
| Automatic and code discounts: type, Shopify's summary of what they give, status, dates, combinations, codes (or their count for bulk sets) and usage limits. Never written: a plan lists differences as conflicts, since a discount changes what customers pay. Two discounts with the same title are reported instead of matched. |
|
| Translations of products, pages, collections, metaobjects, menus and policies. Registered against the target's own text, after the content itself is synced. A translated field only the target has is kept. The plan warns when a language isn't added to the target. |
products, metafields, translations and discounts are read only when you ask for them (resources: ["products"]). Name what you want and only that is read (see Targeted checks). owner_types (--owner-types) limits metafield definitions and values to some owners, e.g. ["SHOP"]. App-owned (app--…) and Shopify-reserved (shopify--…) data is skipped and listed in the report. Shopify's category metafield definitions (namespace shopify, the ones behind storefront filters such as fabric or size) can be compared with include_reserved (--include-reserved); they are never written, so a plan lists them as conflicts to enable in the target's admin.
Files and images referenced by any of the above are matched by file name in the target. When one is missing, the plan says so and apply_plan uploads it from the source store.
What product sync leaves alone. Never copied: sales-channel publishing, the status of existing products, unit cost, videos and 3D models (the target keeps its own), and translations of option names and values. Stock is copied only when asked, into locations with the same name; a location the target doesn't have is skipped. Nothing is ever removed from a target product: a tag, variant or image deleted in the source stays in the target until you remove it there.
Big catalogs. See Built for big catalogs.
Nothing goes live by surprise. New products are drafts and new collections aren't on any sales channel. Pages and metaobject entries copy the published state of the source unless you pass as_drafts; the plan tells you when new ones would be visible right away.
Related MCP server: Shopify MCP Manager
Built for big catalogs
Thousands of products are fine. Above 250 items the tool reads with Shopify bulk exports and writes in batches by itself, instead of one request per item. Comparing a 72-product store with a 4,530-product one went from about 10 hours in version 0.8.0 to 82 seconds since 0.8.1.
Timed live, store to store: 4,000 products with 46,000 variants, images, prices and stock per location, and 85,972 metafield values, copied between two development stores through the MCP tools. Both columns are this tool: version 0.10 wrote through Shopify bulk operations, version 0.11 through batched requests. Other tools and copying by hand were not timed.
Step | This tool 0.10: Shopify bulk operations | This tool 0.11: batched requests |
Diff and plan | 6 min | 6 min |
701 images, created once each | 3 min | 1 min |
4,000 products | 1 h 51 min | 18.5 min |
85,972 metafield values | 1 h 7 min | 25 min |
Total | about 3 h | 51 min |
Why: a Shopify bulk operation writes its items one after the other, about one every five seconds on these stores, and a store runs at most five at once. A few writes per request, twelve requests at once, go about six times faster for products. Metafield values start faster still and then settle at the store's API rate limit, which the tool waits out on its own.
Reads: both stores are listed by handle first, and only the products both have are read in full. A full read of a big catalog is one bulk export.
Writes: new and changed products go a few per request, 12 requests at once, with their variants, prices and stock. Missing images are created first, once each and all at the same time, so no product waits on a download and a shared image isn't copied per product. Metafield values go 100 per request. Measured on a live store, this is several times faster than Shopify's bulk write operations, which stay available with
SYNC_BULK_WRITES=true.Live status: a big apply runs in the background.
apply_statusshows what is written, failed and left per resource type, and the time remaining. Reports list 50 items per section, with counts of the rest.Nothing to set up: it kicks in on its own.
SYNC_BULK_THRESHOLDandSYNC_WRITE_REQUESTStune it.
Use cases
Why this tool
Plenty of Shopify MCP servers read and write one store. This one is built for the job between stores, where every ID is different:
Generic Admin MCP servers | shopify-store-sync-mcp | |
Compare two stores | ❌ | ✅ field-level diff |
Cross-store ID remapping | ❌ you copy raw IDs | ✅ products, collections, pages, blogs, metaobjects, definitions, customer account pages and shop policies |
Dry run before writing | ❌ | ✅ every write goes through a reviewed plan |
Detects changes made after planning | ❌ | ✅ re-reads the target and skips anything that drifted |
Deletes | sometimes | never |
Production guardrails | ❌ | ✅ writes are off by default; protected stores are confirmed by a person, not by the assistant |
Audit trail | ❌ | ✅ JSONL log of every write |
Why not just Shopify CLI? The CLI runs one query you wrote, on one store. This tool uses the CLI only to sign in, and does the comparing, ID remapping, ordering, uploads and safety checks for you.
Compared with store-copy apps
Matrixify, Rewind Staging and Simple Sync also move data from one store to another. Here is what each one states on its own pages (checked November 2026), next to this tool:
shopify-store-sync-mcp | ||||
How it works | Export a spreadsheet from one store, import it into the other | App that copies a store and can keep syncing it | App with manual or daily scheduled syncs | MCP server or CLI on your machine, signed in through Shopify CLI |
What it copies | Products, collections, customers, companies, discounts, orders, pages, blogs, redirects, files, metafields and more, as spreadsheet rows | Products, product images and metafields, collections, metaobjects. Not categories, customers, menus, or metafields on pages and collections | Products and media, collections, metaobjects and definitions, metafields, pages, redirects, blogs, translations, themes, files | See What it syncs: definitions, metaobjects, collections, pages, menus, redirects, policies, files, products, metafield values, translations |
Diff or plan before writing | A dry run checks the file's structure; it doesn't compare with the target store | Not stated | Not stated | Field-level diff of both stores, then a plan you review before anything is written |
Price | Free demo (10 products per file), then $20, $50 or $200 per 30 days | $99 a month, plus $29 per extra store | $129 to $499 a month, by number of target stores | Free, MIT licensed |
"Not stated" means the app's own pages don't describe it, not that it's missing. We haven't timed these apps, so there is no speed claim against them here; our own measured run is in Built for big catalogs. If you've used one of them on a catalog of a similar size, open an issue and your result will be added.
Safe on production
Read-only by default.
allowWritesisfalseuntil you set it, per store.Plan, then apply.
apply_planonly runs a plan produced byplan_sync. Plans expire after an hour and their files are removed after a week.Drift protection. Before writing, the target is re-read. Any item that changed since planning is skipped, not overwritten.
No deletes. Items that exist only in the target are listed, never removed. The same holds inside an item wherever Shopify's API replaces a whole list: menu links, product tags, variants and media that only the target has are read first and sent back with the update. One thing is not kept: when the source has a value for a field and the target has another, the source's value wins. That is what a sync is, and the plan shows each one before you apply.
Protected stores are confirmed by a person. For a store marked
protected, the assistant can't supply the confirmation itself. Your client asks you to type the store's domain (MCP elicitation); in a client that can't ask, the plan is applied from the command line with--confirm <domain>. The assistant sees store content (page bodies, product descriptions), so this is what stands between a prompt hidden in that content and your production store.Conflicts aren't forced. A metafield definition whose type differs is reported and skipped.
Audit log. Every write is appended to
~/.shopify-store-sync/audit.log(override withSYNC_AUDIT_LOG).Snapshot folders are treated as input. A folder used as a source (
dir:) is validated file by file, can only hold the known resource types, and files are only ever uploaded from Shopify's own file hosts. Over MCP, folders are read and written inside one base folder (SYNC_SNAPSHOT_DIR, or the folder the server runs in).No silent shortcuts. A list too long to read fully stops with an error instead of coming back short, and a request that gets no answer is abandoned after a time limit; a write is never repeated blindly.
To report a vulnerability, see SECURITY.md.
Get started
1. Connect your stores
Recommended: sign in with Shopify CLI. No app to create, nothing to paste: run connect and click Install. The other two options are only for scheduled or unattended runs.
npm install -g @shopify/cli # 4.9 or newer
npx shopify-store-sync-mcp connect my-dev-store # read-only
npx shopify-store-sync-mcp connect my-staging-store --writesEach connect opens Shopify in your browser; click Install to approve. It asks for read-only scopes unless you pass --writes (or the store is configured with "allowWrites": true), then prints the line to add to stores.json:
{ "stores": { "my-dev-store": { "domain": "my-dev-store.myshopify.com", "auth": "shopify-cli" } } }It needs Shopify CLI 4.9 or newer; connect checks the version first and says so when it's older.
To compare the metafield definitions of customers, orders and other owners that hold customer data, add their read scopes: connect my-dev-store --scopes read_customers,read_orders. They're left out by default because they open up customer data, and only read scopes can be added this way. A later connect without --scopes drops them again.
Requests then run through shopify store execute, Shopify CLI's supported command, using the sign-in it saved. Each request starts Shopify CLI (about a second), so a full diff takes tens of seconds instead of one or two with an app. That sign-in belongs to you and expires after a while; when it does, the tool says so and you run connect again. Because of that, use option 2 or 3 for scheduled or unattended runs.
One app covers every store in the same Shopify organization, and tokens are fetched and refreshed for you.
Open the Dev Dashboard, go to Apps, click Create app, then Create app manually.
Give it a name, for example
Store Sync. Any URL works as the App URL (it's never opened); untick Embed app in Shopify admin.In Scopes, paste the scopes from "Scopes needed per resource" below, then click Create app and Release.
Install it on each store: open
https://admin.shopify.com/store/<store-handle>/oauth/install?client_id=<your client ID>and click Install.Under the app's Settings, copy the Client ID and Client secret into environment variables (step 2 reads them from there).
Adding a scope later means releasing a new version and approving the update on each store (same install link).
An app's client credentials only work on stores owned by the same organization as the app; elsewhere Shopify answers shop_not_permitted. For a store you don't own there are two ways:
Sign in with Shopify CLI (option 1) with your staff or collaborator account. Nothing to create; best for work you run yourself.
For unattended runs, ask the store's owner to follow option 2 in their organization (create the app in their Dev Dashboard, install it on their store) and share the client ID and client secret with you.
An existing Admin API access token (shpat_...) from a custom app that was created in the store admin still works: use it as accessToken in step 2. New apps of that kind can no longer be created there (Shopify moved app creation to the Dev Dashboard on January 1, 2026), so don't plan new setups around it.
Resource | Read scope | Write scope |
metafield definitions |
|
|
metaobjects and definitions |
|
|
pages |
|
|
menus |
|
|
redirects |
|
|
collections |
|
|
products |
|
|
shop policies |
|
|
metafield values (products, collections, variants, shop) |
|
|
translations |
|
|
files |
|
|
theme diff |
| none, never writes |
discounts |
| none, never writes |
product stock ( |
|
|
ID remapping |
| none |
Metafield definitions of some owner types (customers, orders, draft orders, companies, locations, markets) need that owner's read scope too, such as read_customers. The Shopify CLI sign-in doesn't ask for those, since they open up customer and order data. When a store won't show an owner type, the diff carries on: that owner type is listed as "not compared", on both stores, with the scope Shopify asked for.
Everything at once (the set used for the live tests), ready to paste:
read_products,write_products,read_metaobjects,write_metaobjects,read_metaobject_definitions,write_metaobject_definitions,read_online_store_pages,write_online_store_pages,read_online_store_navigation,write_online_store_navigation,read_legal_policies,write_legal_policies,read_translations,write_translations,read_locales,read_files,write_files,read_themes,read_content,read_discounts,read_inventory,write_inventory,read_locationsGive source stores read-only scopes when you can.
2. Describe your stores
connect prints the line to add. A stores.json mixing all three ways to connect:
{
"stores": {
"dev": { "domain": "my-brand-dev.myshopify.com", "auth": "shopify-cli" },
"eu": { "domain": "my-brand-eu.myshopify.com", "clientId": "env:EU_CLIENT_ID", "clientSecret": "env:EU_CLIENT_SECRET", "allowWrites": true, "protected": true },
"uk": { "domain": "my-brand-uk.myshopify.com", "accessToken": "env:UK_TOKEN" }
}
}Create stores.json. Secrets can come from environment variables with env:NAME:
{
"stores": {
"dev": {
"domain": "my-brand-dev.myshopify.com",
"accessToken": "env:DEV_TOKEN",
"label": "Development"
},
"eu": {
"domain": "my-brand-eu.myshopify.com",
"clientId": "env:EU_CLIENT_ID",
"clientSecret": "env:EU_CLIENT_SECRET",
"allowWrites": true,
"protected": true
}
}
}Option | Default | Meaning |
| required |
|
|
| |
| Static Admin API token from an existing custom app, or | |
| Dev Dashboard app; tokens are fetched and refreshed automatically | |
|
| Admin API version |
|
| Must be |
|
| Applying also needs a person to confirm with the store's domain: asked by your AI client, or |
You can also pass the whole config as JSON in SHOPIFY_STORES, or point SHOPIFY_STORES_FILE at a file elsewhere. For a single store, SHOPIFY_STORE_DOMAIN plus SHOPIFY_ACCESS_TOKEN works.
Variable | Default | Meaning |
|
| Where the store config lives |
| The whole store config as inline JSON | |
|
| Admin API version for stores that don't set |
|
| Path to Shopify CLI, when it isn't on the |
| folder the server runs in | Over MCP, snapshot folders ( |
| off |
|
|
| How long one request to Shopify may take |
|
| How long one Shopify CLI call may take before it is stopped |
|
| Longest list read from a store; a longer one is an error, never a silent cut |
|
| How many independent writes run at once |
|
| Above this many items, products and metafield values are read with a Shopify bulk export and written in batches instead of one request each |
|
| How many batched write requests run at once on one store |
| off |
|
|
| How long a bulk operation may go without writing anything more before it is given up on (a big one may run for hours) |
|
| Plans with more steps than this are applied in the background; follow them with |
|
| With |
|
| With the Shopify CLI sign-in, how many |
|
| Where every write is logged |
|
| Where plans and the audit log are kept |
3. Add it to your AI client
{
"mcpServers": {
"shopify-store-sync": {
"command": "npx",
"args": ["-y", "shopify-store-sync-mcp"],
"env": { "SHOPIFY_STORES_FILE": "/absolute/path/to/stores.json" }
}
}
}Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"shopify-store-sync": {
"command": "npx",
"args": ["-y", "shopify-store-sync-mcp"],
"env": {
"SHOPIFY_STORES_FILE": "/absolute/path/to/stores.json",
"DEV_TOKEN": "shpat_...",
"EU_CLIENT_ID": "...",
"EU_CLIENT_SECRET": "..."
}
}
}
}Claude Code
claude mcp add shopify-store-sync \
-e SHOPIFY_STORES_FILE=/absolute/path/to/stores.json \
-e DEV_TOKEN=shpat_... \
-- npx -y shopify-store-sync-mcpCursor (.cursor/mcp.json) takes the same command, args and env as Claude Desktop.
4. Ask
"Compare dev and eu. Only metaobjects and menus."
"Which product metafield definitions in namespace custom are missing from eu?" (uses
include: ["PRODUCT.custom.*"])"Plan a sync of the faq and size_guide metaobjects from dev to eu."
"Apply only ops 1 to 4 of that plan."
"Sync the pages from dev to eu, but keep new ones hidden." (uses
as_drafts: true)"Copy the linen-shirt product to eu, with its prices." (uses
resources: ["products"], include: ["linen-shirt"], prices: true)"Copy the French translations from dev to eu." (uses
resources: ["translations"], locales: ["fr"])"Export eu's configuration to ./store-config so I can commit it."
"Has eu drifted from ./store-config?"
"What's different in the theme settings between dev and eu?"
"Is the size_guide/shirts entry the same on dev and eu, and does everything it links to exist on eu?" (uses
compare_item)
Targeted checks
You don't have to diff a whole store. Name what you want, and the tool reads only that where Shopify allows it:
To compare | Use | What is read |
One item, side by side |
| That item, plus a lookup of everything it points at, to tell you what's missing in the target |
Some resource types |
| Those types only |
Metaobject entries |
| The named entries (looked up by handle), or only the matching types |
Collections, products |
| Those handles, looked up directly |
Metafield definitions |
| Those owner types |
Metafield values |
| Those owners (and namespace) |
Translations |
| That language |
Pages, menus, redirects and policies are always read in full (they're few, or Shopify has no direct lookup for them), then filtered. Every report starts with what was compared, so a narrow check is never mistaken for a full one.
Tools
What diff_stores reports, field by field (real output):
Tool | Writes? | What it does |
| no | Configured stores and their write permissions, and the server's version. Secrets are never returned. |
| no | What can be synced and how it's keyed. |
| no | Read one store's configuration in portable form. |
| no | One item side by side: each field that differs, and whether what it points at exists in the target. Reads only that item where possible. |
| no | Only-in-source, changed (field by field, and entry by entry inside JSON values), only-in-target. |
| no | Dry-run plan: creates, updates, conflicts, missing references. Returns a |
| no | Show a plan, or list recent ones. |
| yes | Execute a plan, with every safety check above. For a protected store your client asks you to confirm. A plan of more than 50 steps runs in the background and this returns at once. |
| no | How far an apply has got: written, failed and left per resource type, phase, time so far and time remaining, failures counted per reason. Also answers after a server restart. |
| stops writes | Stop a running apply and the Shopify bulk operations it started. What was written stays written. |
| no | Read what an apply wrote, newest first: one entry per step with its outcome. Filter by plan, outcome or resource type. |
| local files only | Write a store's configuration to a folder for git (config as code). |
| no | Compare theme templates and settings between two stores (theme settings). |
Every tool except apply_plan and cancel_apply is read-only toward Shopify and annotated as such, so clients can auto-approve them. Long calls report progress (what was read, which step was written) to clients that ask for it.
Command line
Everything also works without an AI client, and --exit-code turns diff into a scheduled drift check.
Everything also works without an AI client. Run a command instead of starting the server:
npx shopify-store-sync-mcp stores
npx shopify-store-sync-mcp diff dev eu --resources pages,menus
npx shopify-store-sync-mcp check dev eu metaobjects size_guide/shirts
npx shopify-store-sync-mcp plan dev eu --as-drafts
npx shopify-store-sync-mcp plan stg dev --resources products,metafields --with-prices --with-inventory
npx shopify-store-sync-mcp apply <plan-id> --confirm my-brand-eu.myshopify.com
npx shopify-store-sync-mcp export eu ./store-config
npx shopify-store-sync-mcp themes dev eu --ignore-settings "current.sections.header.*"
npx shopify-store-sync-mcp diff dev eu --format md > drift-report.mdLong commands show what they're doing on stderr: what was read, which step is being written and roughly how long is left, and a "still working" line every 10 seconds when nothing else happens (--quiet turns it off). --json gives machine-readable output with every value in full, --format md a Markdown report for a ticket, a pull request or a client, and --exit-code makes diff and themes exit with 2 when they find differences, handy for a scheduled drift check. Run npx shopify-store-sync-mcp help for every option.
Config as code
Export a store's setup as small, sorted JSON files, commit it, and use the folder as a source anywhere (dir:./store-config) to spot drift, review changes as a pull request, or restore.
Export a store's configuration as one small JSON file per item, with sorted keys and no store-specific IDs, then commit it:
npx shopify-store-sync-mcp export prod ./store-config
git add store-config && git commit -m "Snapshot prod configuration"Any command or tool that takes a source also takes dir:<path>:
Spot drift:
diff dir:./store-config prodshows what changed in production since the commit.Review changes: edit the files or re-export from staging, and review the change as a pull request.
Restore or promote:
plan dir:./store-config prod, thenapply, with all the usual safety checks.
diff_themes (or themes on the command line) compares the published themes of two stores: JSON templates, section groups and config/settings_data.json, setting by setting. Pass theme ids to compare other themes, and files to narrow it down (for example templates/product*.json). Settings that differ on purpose between stores (a header logo, an announcement bar, market colors) can be left out with ignore_settings (--ignore-settings): globs on the setting's path, optionally limited to a file, such as current.sections.header.* or config/settings_data.json:current.color_*. The report says how many differences were left out. It is read-only: themes are never written to.
How it works
Every Shopify ID is store-specific, so the server never compares or copies raw IDs. When it reads a store, each gid://shopify/... value is rewritten into a portable reference:
gid://shopify/Product/8123456 → shopify://Product/linen-shirt
gid://shopify/Metaobject/2918 → shopify://Metaobject/faq/returns
gid://shopify/MetaobjectDefinition/77 → shopify://MetaobjectDefinition/faq
gid://shopify/CustomerAccountPage/12 → shopify://CustomerAccountPage/orders
gid://shopify/ShopPolicy/5 → shopify://ShopPolicy/PRIVACY_POLICY
gid://shopify/Menu/41 → shopify://Menu/main-menu
gid://shopify/MetafieldDefinition/9 → shopify://MetafieldDefinition/PRODUCT.custom.fabric
gid://shopify/ProductVariant/4412 → shopify://ProductVariant/linen-shirt/Size%3DM
gid://shopify/Shop/1 → shopify://Shop
gid://shopify/MediaImage/730 → shopify://File/size-chart.pngThis covers JSON list values (list.product_reference) and definition validations (metaobject_definition_id). When it writes, references are resolved by handle in the target. A reference that doesn't exist there is flagged in the plan before anything is written.
Things in the same plan can depend on each other, for example a metaobject pointing at another one being created, or a definition that references itself. These are written in two passes: first without the pending references, then complete.
Files (images, generic files and videos) are matched by file name and uploaded to the target when missing. Collection rules that filter on a metafield are remapped to the target's definition.
Not remapped yet: product variants and articles. Their values are left out of the sync and listed as warnings, never copied as broken IDs.
Two references followed from the source store to the target, as the sample sync above wrote them:
Tested on real stores
Feature | Live result |
Diff of all default resource types | both stores read in about 2 seconds with an app, about 30 through the Shopify CLI sign-in |
Create: metafield and metaobject definitions, metaobjects, smart collection, page, redirect, French translation | applied, second diff empty |
File reference on a metaobject | image uploaded to the target by file name and linked |
Update: page title and body, collection description | applied, second diff empty |
Shop policies | synced; a policy Shopify manages automatically is reported with how to unblock it |
Metafield values, including a | applied, reference remapped to the target's own product |
Values on products missing from the target | skipped up front with the reason |
Export to a folder, then diff that folder against the store | no differences |
Theme settings diff | read-only, 15 files compared in about 1 second |
Products (Shopify CLI sign-in, Windows) | a real product copied as a draft with its 4 images and alt text; after editing the copy and adding a variant and an image there, the update restored the title and kept both; the next diff was identical |
Products: reading only named handles | planning one product went from 97 to 6 seconds |
Big catalog store to store (0.11.0, MCP, Windows) | 4,000 products, 46,000 variants with prices and stock, 701 images and 85,972 metafield values in 51 minutes from plan to finish, 0 products failed; timings above |
Menus (0.5.0) | a link added only in the target stayed in place through an update that added a link from the source; the plan named it; the next plan was empty |
Products: what only the target has (0.5.0) | a tag and a YouTube video added only in the target were both still there after an update that renamed the product and added a tag |
Protected store over MCP (0.5.0, stdio, Windows) | refused when the assistant passed the domain itself; applied after the person typed it when the client asked |
Snapshot folders over MCP (0.5.0) | a folder outside the base folder was refused |
Safety: write to a read-only store | refused |
Safety: target edited after the plan was made | step skipped, nothing overwritten |
Shopify CLI sign-in on Windows (CLI 4.9.4), both stores |
|
Behaviours of the live API found this way are covered by tests: nodes returns null for customer account pages (they're looked up by listing instead), ShopPolicy.type has to be aliased next to Metaobject.type, Shopify refuses edits to auto-managed policies, and a failed token request carries its reason (such as app_not_installed) in an HTML page.
Roadmap
Shipped
Syncing
Metafield definitions, metaobject definitions and metaobject entries
Products: content, category, options, images, variants matched by option values (SKU, barcode, weight, customs, shipping, variant image); new ones as drafts, prices and stock only when asked
Big catalogs: bulk reads, and bulk writes for new products and metafield values
Collections with smart-collection rules, pages, menus (3 levels, customer account menus too), redirects, store policies
Metafield values on products, collections, product variants and the shop, translations per language, products included (opt-in)
Images and files matched by file name, uploaded to the target when missing
Cross-store ID remapping by handle, including list references and rules on metafield definitions
Two-pass writes for items that point at each other or at themselves
Filters: resource types, include and exclude patterns, namespaces, metaobject types, owner types, languages
as_drafts: new pages hidden, new metaobject entries as drafts, published state of existing ones left aloneCompared only, never written: discounts (automatic and code) and Shopify's category metafield definitions
Safety
Dry-run plans that expire after an hour, applied in full or step by step (
--only)Drift check before every write, read-only by default
Never deletes, also inside an item: menu links, product tags, variants and media that only the target has are kept
Protected stores are confirmed by a person (asked by the client, or
--confirmon the command line), never by the assistantConflicts reported instead of forced (type changes, manual versus smart collections, values on items missing from the target)
Snapshot folders validated, files uploaded only from Shopify's hosts, folders kept inside a base folder over MCP
Time limits on every request, and an error instead of a shortened list
Audit log of every write
Ways to use it
MCP server with 10 tools, read-only tools annotated for auto-approval, progress reported on long calls
Command line with
--jsonoutput (values never shortened),--format mdreports,--exit-codefor scheduled drift checks, and progress with time leftTargeted checks: one item side by side (
check,compare_item), and include patterns that limit what is readConfig as code: export a store to files and use the folder as a source (
dir:)Read-only theme settings diff, with settings that differ on purpose left out
JSON values (json metafields, settings) compared entry by entry
Connect without creating an app (Shopify CLI sign-in), or with a Dev Dashboard app or an access token
Published on npm, runs with
npx
Quality
163 automated tests against an in-memory Shopify, plus MCP protocol tests
Every GraphQL operation validated against Shopify's schema for 2026-04, 2026-10 and 2027-01
Tested live between two stores on Linux and Windows, Shopify CLI 4.9 and 5
Parallel reads and writes (metaobject types read and entries written in parallel; the check before writing re-reads only what the plan touches) with throttle-aware retries; clear errors for missing installs, expired sign-ins and auto-managed policies
Linted, no known vulnerabilities in any dependency, release checklist for Shopify's quarterly API versions
Next
Move collection rules to Shopify's new
sourcesmodel.ruleSetis deprecated but supported through 2027-01; the new model only exists from 2026-07, so this waits until 2026-04 can be droppedBulk writes for product updates and redirects (
urlRedirectImport); new products and metafield values already go in bulkProduct prices per market, as an explicit opt-in
Translations of option names and values
Remap blog articles, so references to them sync too
Metafield values on pages and blogs; metafield definition constraints
Menu item (link) translations
Markets and market web presences
Discounts: sync them, behind an explicit flag (compared only today)
Undo: restore the previous values of an applied plan from the audit log
Optional deletes, behind an explicit flag
We're open to recommendations: ideas, feature requests and PRs are all welcome, through an issue. Issues tagged good first issue are a good place to start.
npm install # Node 22 or newer
npm test # vitest: unit, sync engine against an in-memory Shopify, and MCP protocol tests
npm run typecheck
npm run lint
npm run build
# Validate every GraphQL operation against Shopify's real Admin schema
npm run validate:graphql # defaults to 2026-10
npm run validate:graphql -- 2027-01
npm run check # typecheck, lint, tests and schema validation in one goLayout:
src/
index.ts entrypoint: MCP server on stdio, or the CLI when given a command
engine.ts everything the tools and the CLI do, in one place
server.ts MCP tools
cli.ts command line
snapshotFiles.ts export and read snapshot folders (config as code)
themes.ts read-only theme settings diff
config.ts store config loading and validation
shopify/client.ts Admin GraphQL client (token refresh, throttling, retries)
shopify/cliClient.ts the same requests through Shopify CLI's sign-in (`shopify store execute`)
refs.ts GID <-> portable reference mapping
snapshot.ts read a store into portable form
drafts.ts the "as drafts" view: published state left out
diff.ts field-level diff
plan.ts dry-run plans and plan storage
apply.ts guarded, drift-checked, two-pass writes
resources/ one adapter per resource type
test/
fakeShop.ts in-memory Admin API used by the testsAdding a resource type means writing one adapter (fetch, create, update) in src/resources/. See CONTRIBUTING.md, which also has the release checklist.
Syncing definitions between stores isn't a new idea, and these tools are worth knowing:
Project | Type | What it covers |
CLI | Metafield and metaobject definitions plus resource data; dry run by default; has a delete mode | |
CLI | Metafield and metaobject definitions and entries; manifest-based copy; bulk mode deletes the target first | |
CLI | Copies metafield and metaobject definitions | |
MetaMaintain, Metora, Rewind Staging | Shopify apps (paid or freemium) | Definition and entry sync through an embedded app |
What this project adds: it runs inside your AI client as an MCP server (or as a CLI) on your own machine, signed in as you through Shopify CLI or with your own private app, so there's no third-party app from the App Store and no data goes anywhere except Shopify. You can ask for a diff in plain language; it also covers products, pages, menus, redirects, collections, policies, metafield values and translations, remaps references and files across stores, keeps store configuration in git, checks for drift before writing and never deletes. If you only need a scripted one-shot copy of definitions, one of the CLIs above may be all you need.
Disclaimer
Not affiliated with, endorsed by or sponsored by Shopify Inc. "Shopify" is a trademark of Shopify Inc. Test on development stores first; you are responsible for what you apply to production.
License
MIT © Youssef Idder
Available Tools
13 toolsapply_planApply a planADestructive
Write a reviewed plan to the target store. Refused unless the target has allowWrites=true. For a protected store the person is asked to confirm in the client (or applies from the command line); the assistant can't confirm on their behalf. Re-reads the target first and skips anything that changed since planning. Uploads missing files. Creates and updates only, never deletes. Every op is written to the audit log (get_audit_log). Returns { plan_id, status, totals (created, updated, skipped, failed), results per op }; a plan of more than 50 steps runs in the background instead and returns at once: follow it with apply_status and stop it with cancel_apply. A plan can be applied once, within an hour of plan_sync.
Inputs: plan_id (required), only, wait, confirm.
apply_statusFollow an applyARead-only
How far an apply has got: steps created, updated, skipped, failed and left per resource type, the current phase, progress inside a Shopify bulk operation, time so far and an estimate of the time left, failures counted per resource type and reason, and the latest failures. Also answers for an apply that ended or was interrupted by a server restart. Call it after apply_plan returns a background apply, every minute or so until state is done or error. resource narrows only the listed failures; the counts always cover every resource type. For what each step wrote use get_audit_log, to stop the apply use cancel_apply, and for what was planned use get_plan.
Inputs: plan_id, failures, resource.
cancel_applyCancel an applyAIdempotent
Stop an apply that is running in the background: no further step is started and the Shopify bulk operations it started are cancelled. What was already written stays written (nothing is rolled back or deleted). Also stops bulk operations left running by an apply whose server was restarted. If the apply has already ended, nothing is cancelled and its final state is returned. Returns { plan_id, state (cancelling, or interrupted for an apply from before a restart), note }. Follow with apply_status, then plan_sync to see what is left.
Inputs: plan_id.
compare_itemCompare one itemARead-only
Compare a single item between two stores, side by side: whether each has it, every field that differs (entry by entry inside JSON values), and whether the items it points at (products, pages, metaobjects...) exist in the target. Reads only that item where possible, so it is quick. Returns { status (identical, different, only in source, only in target, in neither), changes, refs, notCompared }. Use it for a targeted check instead of diff_stores; take the key from a diff_stores result.
Inputs: key (required), source (required), target (required), resource (required), +1 more.
diff_storesDiff two storesARead-only
Compare configuration between a source and a target, resource type by resource type. Returns for each type the counts (onlyInSource, changed, onlyInTarget, identical) and the keys in each section, with before and after values for every changed field (show_values=false keeps only the field paths); limit caps each list while the counts cover everything, and format="markdown" gives a report to share. Either side can be a snapshot folder ("dir:"), e.g. to check whether production drifted from the committed config. The options shared with plan_sync (resources, include, prices, inventory, as_drafts...) only decide what is read and compared, so the diff matches the plan the same options would produce; nothing is written. Use compare_item for a single item, diff_themes for theme settings, and plan_sync to prepare the changes.
Inputs: source (required), target (required), limit, format, +12 more.
diff_themesCompare theme settingsARead-only
Compare theme configuration between two stores: JSON templates, section groups and settings_data.json (default files: templates/.json, sections/.json, config/settings_data.json). Use it for theme settings; use diff_stores for store data such as metafields, metaobjects and pages. Compares the published themes unless source_theme or target_theme give theme ids. Returns file counts (onlyInSource, changed, onlyInTarget, identical), the files on one side only, and for each changed file the settings that differ with both values (first 100 per file); format="markdown" gives a report. Use ignore_settings to quiet settings that differ on purpose. Never writes to a theme; both stores need the read_themes scope.
Inputs: source (required), target (required), files, format, +4 more.
export_snapshotExport a store's configuration to filesA
Save a store's configuration to a folder on disk, one JSON file per item (sorted keys, no store IDs), ready to commit to git. dir must be new, empty, or an earlier snapshot folder (its item files are replaced); any other folder is refused. Returns a summary { dir, files, kinds } with the count per resource type, not the data; to see the data in the response use snapshot_store. Later, pass "dir:" as the source of diff_stores or plan_sync to compare against it or restore from it. Reads the store and writes only local files, never to Shopify.
Inputs: dir (required), store (required), prices, exclude, +9 more.
get_audit_logRead the audit logARead-only
Read what apply_plan wrote: the most recent audit log entries, newest first, one per step (plan, target store, resource type, key, outcome and message). Filter by plan, outcome (created, updated, skipped, failed) or resource type. Returns { log (file path), matched, returned, entries }: limit (default 50) caps the entries while matched counts every match; in a very large log only the most recent 8 MB is searched. Use it after an apply to see exactly what was written; use apply_status for the progress of a running apply and get_plan for what a plan intended. The log is a local file; nothing is read from Shopify.
Inputs: limit, outcome, plan_id, resource.
get_planGet a planARead-only
Show a sync plan made by plan_sync, before or after it is applied. With plan_id: the plan as plan_sync returned it (totals, ops with field changes, warnings, expiry) plus, once applied, the apply's state and totals; only the first 200 ops are listed and long values are shortened unless full=true, and format="markdown" gives a report to share for review. Without plan_id: the 20 most recent plans (plan_id, createdAt, status, source, target, op count), to find one. To create a plan use plan_sync, to write it use apply_plan, and to follow a running apply use apply_status. Reads only the plans saved by this server, nothing from Shopify.
Inputs: full, format, plan_id.
list_resource_typesList syncable resource typesARead-only
List the resource types this server can snapshot, diff and sync (metafield definitions, metaobjects, pages, menus, products...). Returns [{ kind, default, description }]: kind is the value to pass in the resources argument of snapshot_store, export_snapshot, diff_stores and plan_sync; default tells whether it is read when resources is omitted; description says how items are keyed and what is copied. Use it to choose resources; use list_stores for the stores themselves. Takes no arguments and makes no Shopify calls.
Inputs: no named parameters.
list_storesList configured storesARead-only
List the Shopify stores this server is configured for. Call it first: the aliases it returns are the store names every other tool takes (source, target, store). Returns { server, stores: [{ alias, domain, label, apiVersion, auth, allowWrites, protected }] }. allowWrites=false means apply_plan refuses that store; protected=true means a person confirms every apply to it. An empty list means no store is set up yet. Tokens and secrets are never returned. Takes no arguments and makes no Shopify calls. Next: list_resource_types for what can be synced, diff_stores to compare two stores.
Inputs: no named parameters.
plan_syncPlan a syncARead-only
Build a dry-run plan that would make the target store match the source (a store or a "dir:" snapshot folder) for the selected resources. Reads both sides and writes nothing. Returns { plan_id, expiresAt, totals (create, update, conflict), byResource, ops, warnings, filesToUpload, onlyInTarget, targetWritable, targetProtected }; each op has a seq number, key, action, reason, missing references and field changes (the first 200 ops are listed). Conflicts are items that can't be written, with the reason; items only in the target are listed and never deleted. Show the plan to the person, then pass plan_id to apply_plan; it expires after one hour, and get_plan shows it again. To only look at differences, use diff_stores instead.
Inputs: source (required), target (required), prices, exclude, +9 more.
snapshot_storeSnapshot a storeARead-only
Read one store's configuration (or a snapshot folder made with export_snapshot) and return it in the response, in portable form with store IDs replaced by handles. Returns { store, domain, takenAt, resources: [{ kind, count, items }] }: items are keys only, or { key, data } with full=true, which can be large, so narrow first with resources, include or the other filters. Use it to inspect one store; to save the configuration to files use export_snapshot, and to compare two stores use diff_stores. Writes nothing.
Inputs: store (required), full, prices, exclude, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a distinct role in a clear pipeline: discovery (list_stores, list_resource_types), inspection (snapshot_store, export_snapshot), comparison (diff_stores, compare_item, diff_themes), planning (plan_sync, get_plan), execution (apply_plan, apply_status, cancel_apply) and audit (get_audit_log). The potentially confusable cluster (snapshot vs export vs diff vs compare) is explicitly delimited in every description with 'use X for..., use Y for...' guidance.
Most names follow a predictable verb_noun pattern (list_stores, snapshot_store, export_snapshot, diff_stores, compare_item, apply_plan, get_audit_log). A couple of deviations break the pattern — plan_sync is noun_verb rather than create_plan/plan_changes, and apply_status reads like a status noun rather than get_apply_status — but the overall scheme stays readable.
13 tools is well within the ideal range and each maps to a needed stage of the sync lifecycle; nothing looks redundant or padded. Read-only inspection, planning, applying, monitoring and auditing each justify their slots.
Coverage is strong: discovery, snapshot/export, diff, dry-run planning, gated apply, progress tracking, cancellation and audit logging, plus restore-from-folder via 'dir:<path>' sources. The main gap is diff_themes, which compares theme files but has no corresponding apply tool, so theme changes are a dead end; deletion is also absent, though that is an explicitly stated design choice.
Maintenance
Related MCP Connectors
Build, deploy and manage MaShop e-commerce projects from Claude, Cursor or any MCP client.
Hosted Shopify MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Unofficial Shopify MCP Pack — wraps the Shopify Admin REST API (2024-01)
Manage WordPress blogs and WooCommerce shops from Claude, ChatGPT, Cursor and other MCP apps.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAI-powered Shopify Admin via Claude + MCP, enabling full store management through conversation including products, collections, analytics, and bulk operations.-
- AlicenseCqualityDmaintenanceEnables AI assistants like Cursor or Claude Desktop to fully manage a Shopify store using the Model Context Protocol, with tools for products, orders, customers, inventory, discounts, and analytics.32MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that connects Claude to Shopify stores, enabling natural language queries and actions on products, orders, customers, inventory, and sales analytics. Includes a demo mode with bundled fixtures for trying tools without credentials.MIT
- AlicenseAqualityBmaintenanceMCP server for building Shopify stores with AI, letting Claude Code and other clients edit themes, pages, and navigation via the Admin GraphQL API. Credentials stay on your machine as the server runs locally.913 npm3ISC