mcp-shopify-yoffi 1.2.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,709 +1,711 @@
1
- # Shopify MCP Server (Yoffi Digital fork)
2
-
3
- MCP Server for the Shopify Admin API, enabling interaction with store data through GraphQL. This server provides tools for managing products, customers, orders, discounts, and more.
4
-
5
- This is a fork of [shopify-mcp](https://github.com/GeLi2001/shopify-mcp) by GeLi2001, extended by [Yoffi Digital](https://github.com/yoffi-digital) with discount-management tools (`create-discount`, `create-automatic-discount`) and other fixes.
6
-
7
- ## Features
8
-
9
- - **Product Management**: Full CRUD for products, variants, and options (8 tools)
10
- - **Customer Management**: Full CRUD, merge, and address management (8 tools)
11
- - **Order Management**: Smart lookup, cancel, close/open, mark as paid, fulfillment, refunds (10 tools)
12
- - **Metafield Management**: Get, set, and delete metafields on any resource (3 tools)
13
- - **Inventory Management**: Set absolute inventory quantities at locations (1 tool)
14
- - **Tag Management**: Add/remove tags on any taggable resource (1 tool)
15
- - **Discount Management**: Create percentage or fixed-amount discount codes, store-wide or scoped to collections, bulk-attach thousands of codes to an existing discount, pause/reschedule/delete discounts, export or remove codes (7 tools)
16
- - **Translation Management**: List shop locales, read translatable content, and register or remove translations (4 tools)
17
- - **Metaobject & File Management**: Read definitions, list/create/update/delete metaobject entries, search and upload files (6 tools)
18
- - **Pagination & Sorting**: Cursor-based pagination and sort keys on all list queries
19
- - **Advanced Filtering**: Pass-through Shopify query syntax for all list endpoints
20
- - **GraphQL Integration**: Direct integration with Shopify's GraphQL Admin API (2026-01)
21
- - **Comprehensive Error Handling**: Clear error messages for API and authentication issues
22
-
23
- ## Prerequisites
24
-
25
- 1. Node.js (version 18 or higher)
26
- 2. A Shopify store with a custom app (see setup instructions below)
27
-
28
- ## Setup
29
-
30
- ### Authentication
31
-
32
- This server supports two authentication methods:
33
-
34
- #### Option 1: Client Credentials (Dev Dashboard apps, January 2026+)
35
-
36
- As of January 1, 2026, new Shopify apps are created in the **Dev Dashboard** and use OAuth client credentials instead of static access tokens.
37
-
38
- 1. From your Shopify admin, go to **Settings** > **Apps and sales channels**
39
- 2. Click **Develop apps** > **Build app in dev dashboard**
40
- 3. Create a new app and configure **Admin API scopes**:
41
- - `read_products`, `write_products`
42
- - `read_customers`, `write_customers`
43
- - `read_orders`, `write_orders`
44
- - `read_locales`, `read_translations`, `write_translations` (for the translation tools)
45
- - `read_metaobject_definitions`, `read_metaobjects`, `write_metaobjects`, `read_files`, `write_files` (for the metaobject and file tools)
46
- 4. Install the app on your store
47
- 5. Copy your **Client ID** and **Client Secret** from the app's API credentials
48
-
49
- The server will automatically exchange these for an access token and refresh it before it expires (tokens are valid for ~24 hours).
50
-
51
- #### Option 2: Static Access Token (legacy apps)
52
-
53
- If you have an existing custom app with a static `shpat_` access token, you can still use it directly.
54
-
55
- This package is not currently published to npm — clone the repo and build it locally:
56
-
57
- ```bash
58
- git clone https://github.com/yoffi-digital/mcp-shopify-yoffi.git
59
- cd mcp-shopify-yoffi
60
- npm install
61
- npm run build
62
- ```
63
-
64
- This produces `dist/index.js`, which the commands below reference directly.
65
-
66
- ### Usage with Claude Desktop
67
-
68
- **Client Credentials (recommended):**
69
-
70
- ```json
71
- {
72
- "mcpServers": {
73
- "shopify": {
74
- "command": "node",
75
- "args": [
76
- "/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
77
- "--clientId",
78
- "<YOUR_CLIENT_ID>",
79
- "--clientSecret",
80
- "<YOUR_CLIENT_SECRET>",
81
- "--domain",
82
- "<YOUR_SHOP>.myshopify.com"
83
- ]
84
- }
85
- }
86
- }
87
- ```
88
-
89
- **Static Access Token (legacy):**
90
-
91
- ```json
92
- {
93
- "mcpServers": {
94
- "shopify": {
95
- "command": "node",
96
- "args": [
97
- "/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
98
- "--accessToken",
99
- "<YOUR_ACCESS_TOKEN>",
100
- "--domain",
101
- "<YOUR_SHOP>.myshopify.com"
102
- ]
103
- }
104
- }
105
- }
106
- ```
107
-
108
- Locations for the Claude Desktop config file:
109
-
110
- - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
111
- - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
112
-
113
- ### Usage with Claude Code
114
-
115
- **Client Credentials:**
116
-
117
- ```bash
118
- claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
119
- --clientId YOUR_CLIENT_ID \
120
- --clientSecret YOUR_CLIENT_SECRET \
121
- --domain your-store.myshopify.com
122
- ```
123
-
124
- **Static Access Token (legacy):**
125
-
126
- ```bash
127
- claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
128
- --accessToken YOUR_ACCESS_TOKEN \
129
- --domain your-store.myshopify.com
130
- ```
131
-
132
- ### Alternative: Run Locally with Environment Variables
133
-
134
- If you prefer to use environment variables instead of command-line arguments:
135
-
136
- 1. Create a `.env` file with your Shopify credentials:
137
-
138
- **Client Credentials:**
139
- ```
140
- SHOPIFY_CLIENT_ID=your_client_id
141
- SHOPIFY_CLIENT_SECRET=your_client_secret
142
- MYSHOPIFY_DOMAIN=your-store.myshopify.com
143
- ```
144
-
145
- **Static Access Token (legacy):**
146
- ```
147
- SHOPIFY_ACCESS_TOKEN=your_access_token
148
- MYSHOPIFY_DOMAIN=your-store.myshopify.com
149
- ```
150
-
151
- 2. Run the server:
152
- ```
153
- node dist/index.js
154
- ```
155
-
156
- ### Additional Options
157
-
158
- - `--apiVersion`: Specify the Shopify API version (default: `2026-01`). Can also be set via `SHOPIFY_API_VERSION` environment variable.
159
-
160
- ## Available Tools (32)
161
-
162
- ### Pagination, Sorting & Filtering
163
-
164
- All list query tools (`get-products`, `get-customers`, `get-orders`, `get-customer-orders`) support:
165
-
166
- - **Cursor-based pagination**: `after` / `before` (cursor strings), with `pageInfo` in the response (`hasNextPage`, `hasPreviousPage`, `startCursor`, `endCursor`)
167
- - **Sorting**: `sortKey` (enum specific to each resource) and `reverse` (boolean)
168
- - **Advanced filtering**: `query` or `searchQuery` parameter accepting [Shopify query syntax](https://shopify.dev/docs/api/usage/search-syntax)
169
-
170
- ### Product Management (8 tools)
171
-
172
- 1. **`get-products`**
173
-
174
- - Get all products or search by title with pagination and sorting
175
- - Inputs:
176
- - `searchTitle` (string, optional): Filter products by title (wraps in `title:*...*`)
177
- - `limit` (number, default: 10): Maximum number of products to return
178
- - `query` (string, optional): Raw Shopify query string (e.g. `"status:active vendor:Nike tag:sale"`)
179
- - `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `INVENTORY_TOTAL`, `PRODUCT_TYPE`, `PUBLISHED_AT`, `RELEVANCE`, `TITLE`, `UPDATED_AT`, `VENDOR`
180
- - `reverse` (boolean, optional): Reverse the sort order
181
- - `after` / `before` (string, optional): Pagination cursors
182
-
183
- 2. **`get-product-by-id`**
184
-
185
- - Get a specific product by ID with full details including SEO, options, media, variants, and collections
186
- - Inputs:
187
- - `productId` (string, required): Shopify product GID
188
- - Returns: `productType`, `descriptionHtml`, `seo`, `options` (with `optionValues`), `media` (images), `variants`, `collections`, `tags`, `vendor`, price range, inventory
189
-
190
- 3. **`create-product`**
191
-
192
- - Create a new product. When using `productOptions`, Shopify registers all option values but only creates one default variant (first value of each option, price $0). Use `manage-product-variants` with `strategy: REMOVE_STANDALONE_VARIANT` afterward to create all real variants with prices.
193
- - Inputs:
194
- - `title` (string, required): Title of the product
195
- - `descriptionHtml` (string, optional): Description with HTML
196
- - `handle` (string, optional): URL slug. Auto-generated from title if omitted
197
- - `vendor` (string, optional): Vendor of the product
198
- - `productType` (string, optional): Type of the product
199
- - `tags` (array of strings, optional): Product tags
200
- - `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`. Default `"DRAFT"`
201
- - `seo` (object, optional): `{ title, description }` for search engines
202
- - `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
203
- - `productOptions` (array of objects, optional): Options to create inline, e.g. `[{ name: "Size", values: [{ name: "S" }, { name: "M" }] }]`. Max 3 options.
204
- - `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
205
-
206
- 4. **`update-product`**
207
-
208
- - Update an existing product's fields
209
- - Inputs:
210
- - `id` (string, required): Shopify product GID
211
- - `title` (string, optional): New title
212
- - `descriptionHtml` (string, optional): New description
213
- - `handle` (string, optional): New URL slug
214
- - `vendor` (string, optional): New vendor
215
- - `productType` (string, optional): New product type
216
- - `tags` (array of strings, optional): New tags (overwrites existing)
217
- - `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`
218
- - `seo` (object, optional): `{ title, description }` for search engines
219
- - `metafields` (array of objects, optional): Metafields to set or update
220
- - `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
221
- - `collectionsToLeave` (array of strings, optional): Collection GIDs to remove the product from
222
- - `redirectNewHandle` (boolean, optional): If true, old handle redirects to new handle
223
-
224
- 5. **`delete-product`**
225
-
226
- - Delete a product
227
- - Inputs:
228
- - `id` (string, required): Shopify product GID
229
-
230
- 6. **`manage-product-options`**
231
-
232
- - Create, update, or delete product options (e.g. Size, Color)
233
- - Inputs:
234
- - `productId` (string, required): Shopify product GID
235
- - `action` (string, required): `"create"`, `"update"`, or `"delete"`
236
- - `variantStrategy` (string, optional): `"LEAVE_AS_IS"` (default) or `"CREATE"` — controls whether new variant combinations are generated when adding options
237
- - For `action: "create"`:
238
- - `options` (array, required): Options to create, e.g. `[{ name: "Size", values: ["S", "M", "L"] }]`
239
- - For `action: "update"`:
240
- - `optionId` (string, required): Option GID to update
241
- - `name` (string, optional): New name for the option
242
- - `position` (number, optional): New position
243
- - `valuesToAdd` (array of strings, optional): Values to add
244
- - `valuesToDelete` (array of strings, optional): Value GIDs to remove
245
- - For `action: "delete"`:
246
- - `optionIds` (array of strings, required): Option GIDs to delete
247
-
248
- 7. **`manage-product-variants`**
249
-
250
- - Create or update product variants in bulk
251
- - Inputs:
252
- - `productId` (string, required): Shopify product GID
253
- - `strategy` (string, optional): How to handle the default variant when creating. `"DEFAULT"` (removes "Default Title" automatically), `"REMOVE_STANDALONE_VARIANT"` (recommended for full control), or `"PRESERVE_STANDALONE_VARIANT"`
254
- - `variants` (array, required): Variants to create or update. Each variant:
255
- - `id` (string, optional): Variant GID for updates. Omit to create new
256
- - `price` (string, optional): Price, e.g. `"49.00"`
257
- - `compareAtPrice` (string, optional): Compare-at price for showing discounts
258
- - `sku` (string, optional): SKU (mapped to `inventoryItem.sku`)
259
- - `tracked` (boolean, optional): Whether inventory is tracked. Set `false` for print-on-demand
260
- - `taxable` (boolean, optional): Whether the variant is taxable
261
- - `barcode` (string, optional): Barcode
262
- - `weight` (number, optional): Weight of the variant
263
- - `weightUnit` (string, optional): `"GRAMS"`, `"KILOGRAMS"`, `"OUNCES"`, or `"POUNDS"`
264
- - `optionValues` (array, optional): Option values, e.g. `[{ optionName: "Size", name: "A4" }]`
265
-
266
- 8. **`delete-product-variants`**
267
-
268
- - Delete one or more variants from a product
269
- - Inputs:
270
- - `productId` (string, required): Shopify product GID
271
- - `variantIds` (array of strings, required): Variant GIDs to delete
272
-
273
- ### Customer Management (8 tools)
274
-
275
- 1. **`get-customers`**
276
-
277
- - List customers with search, pagination, and sorting
278
- - Inputs:
279
- - `searchQuery` (string, optional): Freetext or Shopify query syntax (e.g. `"country:US tag:vip orders_count:>5"`)
280
- - `limit` (number, default: 10): Maximum number of customers to return
281
- - `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `LAST_UPDATE`, `LOCATION`, `NAME`, `ORDERS_COUNT`, `RELEVANCE`, `TOTAL_SPENT`, `UPDATED_AT`
282
- - `reverse` (boolean, optional): Reverse the sort order
283
- - `after` / `before` (string, optional): Pagination cursors
284
-
285
- 2. **`get-customer-by-id`**
286
-
287
- - Get a single customer by ID with full details
288
- - Inputs:
289
- - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
290
- - Returns: name, email, phone, addresses, tags, note, tax status, amount spent, order count, metafields
291
-
292
- 3. **`create-customer`**
293
-
294
- - Create a new customer
295
- - Inputs:
296
- - `firstName` (string, optional): Customer's first name
297
- - `lastName` (string, optional): Customer's last name
298
- - `email` (string, optional): Customer's email address
299
- - `phone` (string, optional): Customer's phone number
300
- - `tags` (array of strings, optional): Tags to apply
301
- - `note` (string, optional): Note about the customer
302
- - `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
303
- - `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
304
- - `addresses` (array of objects, optional): Customer addresses (`address1`, `address2`, `city`, `provinceCode`, `zip`, `country`, `phone`)
305
-
306
- 4. **`update-customer`**
307
-
308
- - Update a customer's information
309
- - Inputs:
310
- - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
311
- - `firstName` (string, optional): Customer's first name
312
- - `lastName` (string, optional): Customer's last name
313
- - `email` (string, optional): Customer's email address
314
- - `phone` (string, optional): Customer's phone number
315
- - `tags` (array of strings, optional): Tags to apply to the customer
316
- - `note` (string, optional): Note about the customer
317
- - `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
318
- - `emailMarketingConsent` (object, optional): Email marketing consent settings
319
- - `marketingState` (string, required): `"NOT_SUBSCRIBED"`, `"SUBSCRIBED"`, `"UNSUBSCRIBED"`, or `"PENDING"`
320
- - `consentUpdatedAt` (string, optional): ISO 8601 timestamp
321
- - `marketingOptInLevel` (string, optional): `"SINGLE_OPT_IN"`, `"CONFIRMED_OPT_IN"`, or `"UNKNOWN"`
322
- - `metafields` (array of objects, optional): Customer metafields
323
-
324
- 5. **`delete-customer`**
325
-
326
- - Delete a customer
327
- - Inputs:
328
- - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
329
-
330
- 6. **`customer-merge`**
331
-
332
- - Merge two customer records into one
333
- - Inputs:
334
- - `customerOneId` (string, required): GID of the first customer
335
- - `customerTwoId` (string, required): GID of the second customer
336
- - `overrideFields` (object, optional): Override which fields to keep from which customer (firstName, lastName, email, phone, defaultAddress, note, tags)
337
-
338
- 7. **`manage-customer-address`**
339
-
340
- - Create, update, or delete a customer's mailing address
341
- - Inputs:
342
- - `customerId` (string, required): Customer GID
343
- - `action` (string, required): `"create"`, `"update"`, or `"delete"`
344
- - `addressId` (string, optional): Address GID (required for update/delete)
345
- - `address` (object, optional): Address fields (required for create/update): `address1`, `address2`, `city`, `company`, `countryCode`, `firstName`, `lastName`, `phone`, `provinceCode`, `zip`
346
- - `setAsDefault` (boolean, optional): Set as customer's default address
347
-
348
- ### Order Management (10 tools)
349
-
350
- 1. **`get-orders`**
351
-
352
- - Get orders with filtering, pagination, and sorting
353
- - Inputs:
354
- - `status` (string, optional): `"any"`, `"open"`, `"closed"`, or `"cancelled"`. Default `"any"`
355
- - `limit` (number, default: 10): Maximum number of orders to return
356
- - `query` (string, optional): Raw Shopify query string (e.g. `"financial_status:paid fulfillment_status:shipped tag:rush"`)
357
- - `sortKey` (string, optional): One of `CREATED_AT`, `ORDER_NUMBER`, `TOTAL_PRICE`, `FINANCIAL_STATUS`, `FULFILLMENT_STATUS`, `UPDATED_AT`, `CUSTOMER_NAME`, `PROCESSED_AT`, `ID`, `RELEVANCE`
358
- - `reverse` (boolean, optional): Reverse the sort order
359
- - `after` / `before` (string, optional): Pagination cursors
360
-
361
- 2. **`get-order-by-id`**
362
-
363
- - Get a specific order by ID with smart lookup — accepts order name (`#77235` or `77235`), numeric ID (`8054938337547`), or full GID (`gid://shopify/Order/...`)
364
- - Inputs:
365
- - `orderId` (string, required): Order name, numeric ID, or full GID
366
- - Returns: pricing, customer, shipping/billing addresses, line items, tags, notes, metafields, cancel reason, return status, discount codes, PO number, timestamps
367
-
368
- 3. **`update-order`**
369
-
370
- - Update an existing order
371
- - Inputs:
372
- - `id` (string, required): Shopify order GID
373
- - `tags` (array of strings, optional): New tags for the order
374
- - `email` (string, optional): Update customer email on the order
375
- - `note` (string, optional): Order notes
376
- - `phone` (string, optional): Phone number for the order
377
- - `poNumber` (string, optional): Purchase order number
378
- - `customAttributes` (array of objects, optional): Custom key-value attributes
379
- - `metafields` (array of objects, optional): Order metafields
380
- - `shippingAddress` (object, optional): Shipping address fields
381
-
382
- 4. **`get-customer-orders`**
383
-
384
- - Get orders for a specific customer with pagination and sorting
385
- - Inputs:
386
- - `customerId` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
387
- - `limit` (number, default: 10): Maximum number of orders to return
388
- - `sortKey` (string, optional): Same sort keys as `get-orders`
389
- - `reverse` (boolean, optional): Reverse the sort order
390
- - `after` / `before` (string, optional): Pagination cursors
391
-
392
- 5. **`order-cancel`**
393
-
394
- - Cancel an order with options for refunding, restocking, and customer notification. **Irreversible.**
395
- - Inputs:
396
- - `orderId` (string, required): Order GID
397
- - `reason` (string, required): `"CUSTOMER"`, `"DECLINED"`, `"FRAUD"`, `"INVENTORY"`, `"OTHER"`, or `"STAFF"`
398
- - `restock` (boolean, required): Whether to restock inventory
399
- - `notifyCustomer` (boolean, default: false): Notify the customer
400
- - `staffNote` (string, optional): Internal note
401
- - `refund` (boolean, optional): Refund to original payment method
402
-
403
- 6. **`order-close-open`**
404
-
405
- - Close or reopen an order
406
- - Inputs:
407
- - `orderId` (string, required): Order GID
408
- - `action` (string, required): `"close"` or `"open"`
409
-
410
- 7. **`order-mark-as-paid`**
411
-
412
- - Mark an order as paid (for manual/offline payments)
413
- - Inputs:
414
- - `orderId` (string, required): Order GID
415
-
416
- 8. **`create-fulfillment`**
417
-
418
- - Create a fulfillment (mark items as shipped) with optional tracking
419
- - Inputs:
420
- - `lineItemsByFulfillmentOrder` (array, required): Fulfillment orders and line items to fulfill
421
- - `trackingInfo` (object, optional): `{ number, url, company }` tracking details
422
- - `notifyCustomer` (boolean, default: false): Send shipping notification
423
-
424
- 9. **`refund-create`**
425
-
426
- - Create a full or partial refund with optional restocking
427
- - Inputs:
428
- - `orderId` (string, required): Order GID
429
- - `refundLineItems` (array, optional): Line items to refund with `lineItemId`, `quantity`, `restockType` (`CANCEL`/`RETURN`/`NO_RESTOCK`), `locationId`
430
- - `shipping` (object, optional): `{ amount, fullRefund }` shipping refund
431
- - `note` (string, optional): Refund note
432
- - `notify` (boolean, optional): Send refund notification
433
-
434
- 10. **`create-draft-order`**
435
-
436
- - Create a draft order for phone/chat sales, invoicing, or wholesale
437
- - Inputs:
438
- - `lineItems` (array, required): Product variants (`variantId`) or custom items (`title` + price). Max 499
439
- - `customerId` (string, optional): Customer GID
440
- - `email`, `phone`, `note`, `tags`, `poNumber` (optional)
441
- - `shippingAddress`, `billingAddress` (objects, optional)
442
- - `appliedDiscount` (object, optional): `{ title, value, valueType }` order-level discount
443
-
444
- ### Draft Order Management (1 tool)
445
-
446
- 1. **`complete-draft-order`**
447
-
448
- - Complete a draft order, converting it into a real order
449
- - Inputs:
450
- - `draftOrderId` (string, required): Draft order GID
451
- - `paymentGatewayId` (string, optional): Payment gateway GID
452
-
453
- ### Metafield Management (3 tools)
454
-
455
- 1. **`get-metafields`**
456
-
457
- - Get metafields for any Shopify resource (products, orders, customers, variants, collections, etc.)
458
- - Inputs:
459
- - `ownerId` (string, required): GID of any resource
460
- - `namespace` (string, optional): Filter by namespace
461
- - `first` (number, default: 25): Number of metafields to return
462
- - `after` (string, optional): Pagination cursor
463
-
464
- 2. **`set-metafields`**
465
-
466
- - Set metafields on any Shopify resource. Creates or updates up to 25 metafields atomically
467
- - Inputs:
468
- - `metafields` (array, required): Metafields to set, each with `ownerId`, `key`, `value`, and optional `namespace`, `type`
469
-
470
- 3. **`delete-metafields`**
471
-
472
- - Delete metafields from any Shopify resource
473
- - Inputs:
474
- - `metafields` (array, required): Metafields to delete, each with `ownerId`, `namespace`, `key`
475
-
476
- ### Inventory Management (1 tool)
477
-
478
- 1. **`inventory-set-quantities`**
479
-
480
- - Set absolute inventory quantities for items at specific locations
481
- - Inputs:
482
- - `reason` (string, required): Reason for change (e.g. `"correction"`, `"cycle_count_available"`)
483
- - `name` (string, required): `"available"` or `"on_hand"`
484
- - `quantities` (array, required): Items with `inventoryItemId`, `locationId`, `quantity`
485
-
486
- ### Tag Management (1 tool)
487
-
488
- 1. **`manage-tags`**
489
-
490
- - Add or remove tags on any taggable resource (orders, products, customers, draft orders, articles)
491
- - Inputs:
492
- - `id` (string, required): GID of the resource
493
- - `tags` (array of strings, required): Tags to add or remove
494
- - `action` (string, required): `"add"` or `"remove"`
495
-
496
- ### Discount Management (7 tools)
497
-
498
- Bulk and maintenance tools (3–7) need the `read_discounts` and `write_discounts` scopes.
499
-
500
- **Finding a discount:** every tool accepts the discount GID, the number from the admin URL (`/discounts/2269857186117`) or any code that is on it. Searching by code only works while that code is still on the discount. If a code was removed (for example the discount's own main code, which `remove-discount-codes` with `keepCsvPath` removes together with every other code not in the list), use the ID from the admin URL or one of the codes that are still on it.
501
-
502
- 1. **`create-discount`**
503
-
504
- - Create a basic discount code (percentage or fixed amount), applied store-wide or scoped to specific collections and/or products
505
- - Inputs:
506
- - `title` (string, required): Internal title for the discount
507
- - `code` (string, required): The discount code customers enter at checkout
508
- - `valueType` (string, required): `"PERCENTAGE"` or `"FIXED_AMOUNT"`
509
- - `value` (number, required): Decimal between 0 and 1 for `PERCENTAGE` (e.g. `0.15` for 15%), or the currency amount for `FIXED_AMOUNT`
510
- - `startsAt` (string, required): ISO 8601 datetime the discount becomes active
511
- - `endsAt` (string, optional): ISO 8601 datetime the discount expires
512
- - `appliesOncePerCustomer` (boolean, optional): Limit each customer to a single use
513
- - `usageLimit` (number, optional): Total number of redemptions allowed
514
- - `includeCollectionIds` (array of strings, optional): Collection GIDs to scope the discount to (mutually exclusive with the product ID fields)
515
- - `excludeCollectionIds` (array of strings, optional): Collection GIDs to exclude from an otherwise store-wide discount
516
- - `includeProductIds` (array of strings, optional): Product GIDs to scope the discount to (mutually exclusive with the collection ID fields)
517
- - `excludeProductIds` (array of strings, optional): Product GIDs to exclude from an otherwise store-wide discount
518
- - `combinesWith` (object, optional): `{ productDiscounts, orderDiscounts, shippingDiscounts }` combination rules
519
-
520
- 2. **`create-automatic-discount`**
521
-
522
- - Create an automatic discount (percentage or fixed amount) that applies at checkout with no code required, store-wide or scoped to specific collections and/or products
523
- - Inputs:
524
- - `title` (string, required): Title for the discount, shown to customers at checkout
525
- - `valueType` (string, required): `"PERCENTAGE"` or `"FIXED_AMOUNT"`
526
- - `value` (number, required): Decimal between 0 and 1 for `PERCENTAGE` (e.g. `0.15` for 15%), or the currency amount for `FIXED_AMOUNT`
527
- - `startsAt` (string, required): ISO 8601 datetime the discount becomes active
528
- - `endsAt` (string, optional): ISO 8601 datetime the discount expires
529
- - `minimumSubtotal` (number, optional): Minimum order subtotal required for the discount to apply
530
- - `includeCollectionIds` (array of strings, optional): Collection GIDs to scope the discount to (mutually exclusive with the product ID fields)
531
- - `excludeCollectionIds` (array of strings, optional): Collection GIDs to exclude from an otherwise store-wide discount
532
- - `includeProductIds` (array of strings, optional): Product GIDs to scope the discount to (mutually exclusive with the collection ID fields)
533
- - `excludeProductIds` (array of strings, optional): Product GIDs to exclude from an otherwise store-wide discount
534
- - `combinesWith` (object, optional): `{ productDiscounts, orderDiscounts, shippingDiscounts }` combination rules
535
-
536
- 3. **`add-discount-codes`**
537
-
538
- - Attach many single-use codes (up to 100,000) to an existing code discount, including app discounts (e.g. SMART). Uploads in batches of 250 and writes two files: `<run>-result.csv` (every code with its status) and `<run>-partner.csv` (only usable codes). Only counts and samples are returned to the chat, never the full code list. Local (stdio) mode only.
539
- - Statuses: `attached`, `skipped` (already on this discount), `conflict` (on another discount), `failed` (with Shopify's reason)
540
- - Safe to repeat: each call stops after `maxSeconds`; calling again with the same input resumes from the result file and never uploads a code twice
541
- - Inputs:
542
- - `discount` (string, required): Discount GID, the number from the admin URL (`/discounts/123`), or a code already on the discount
543
- - `generate` (object, optional): `{ count, prefix, length }`, e.g. `{ count: 25000, prefix: "DB-" }`. Uses readable characters only (no 0/O, 1/I/L)
544
- - `csvPath` (string, optional): Partner CSV with its own codes (`code` column or first column, comma or semicolon). Use this or `generate`
545
- - `outputDir` (string, optional): Folder for the result files. Required with `generate`; defaults to the CSV's folder
546
- - `runName` (string, optional): Name of the result files. A new name starts a new run
547
- - `dryRun` (boolean, default `true`): Show the discount details, plan and warnings without uploading. Reads the discount's current codes, so codes already on it are reported as `alreadyOnDiscount`, not as "would upload"
548
- - `verify` (boolean, default `false`): Code-by-code reconciliation. Pages through all codes on the discount and compares them with the CSV / result file: `ok`, `missing` (in list, not on discount) and `extra` (on discount, not in list). Writes `<run>-verify.csv` and sets missing codes back to pending, so the next run uploads exactly those. Uploads nothing
549
- - `maxSeconds` (number, default 50): Time budget per call
550
- - Resilience: throttled requests are retried (about 47 s), network problems and requests without an answer after 25 s are retried 5 times. If it still fails, the call returns the counts plus `interrupted` instead of an error; calling again continues. `<run>-partner.csv` is written once, when the run is finished. If Windows locks a file (virus scanner, preview), the write is retried and otherwise reported in `fileWarnings` without aborting the call
551
-
552
- 4. **`manage-discount`**
553
-
554
- - Pause (`deactivate`), reactivate (`activate`) or reschedule (change start/end date) an existing code discount, native or app (e.g. SMART). Codes are kept. Returns the discount before and after
555
- - Inputs:
556
- - `discount` (string, required): Discount GID, the number from the admin URL, or one of its codes
557
- - `action` (string, required): `"activate"`, `"deactivate"` or `"reschedule"`
558
- - `startsAt` (string, optional): `reschedule` only, new start (ISO 8601)
559
- - `endsAt` (string or null, optional): `reschedule` only, new end (ISO 8601); `null` removes the end date
560
-
561
- 5. **`delete-discounts`**
562
-
563
- - Permanently delete code discounts including all their codes (e.g. test discounts). Explicit discounts only, never by search. Default `dryRun=true` lists what would be deleted. Discounts already used in orders are skipped unless `allowUsed=true`. Discounts that are not found are reported, so repeating a call is safe
564
- - Inputs:
565
- - `discounts` (array of strings, required, max 50): GID, admin URL number or a code of each discount
566
- - `dryRun` (boolean, default `true`): Only show what would be deleted
567
- - `confirmCount` (number): Required when `dryRun=false`: the number of discounts that would be deleted (`wouldDelete` from the dry run). A wrong or missing number refuses the deletion
568
- - `allowUsed` (boolean, default `false`): Also delete discounts that were used in orders
569
- - `maxSeconds` (number, default 50): How long to wait for Shopify's delete job
570
-
571
- 6. **`get-discount-codes`**
572
-
573
- - Look up a discount by ID, admin URL number or any of its codes (which discount does this code belong to?) and show its details. With `outputDir` it exports all codes to `<run>-codes.csv`; large discounts (25,000+) take several calls, repeat the same input to continue. The chat only gets details, counts and sample codes
574
- - Inputs:
575
- - `discount` (string, required): GID, admin URL number or a code
576
- - `outputDir` (string, optional): Folder for the CSV export (local mode only)
577
- - `runName` (string, optional): Name of the export files
578
- - `maxSeconds` (number, default 50): Time budget per call
579
-
580
- 7. **`remove-discount-codes`**
581
-
582
- - Remove codes from a discount without deleting it, e.g. extra codes after an upload. Three modes: `codes` (explicit list), `removeCsvPath` (codes to remove) or `keepCsvPath` (codes that must stay, everything else is removed). Default `dryRun=true` reads the discount once, builds the plan and writes `<run>-remove-plan.csv` (code + status) and a state file `<run>-remove-state.json`. The first real run needs `confirmCount` equal to the planned count; after that the run is confirmed. Large removals (25,000 codes) continue over several calls: repeat the same input (same `runName`, no `confirmCount`); each call works through the saved plan without re-reading the discount, so it is not affected by the count changing while Shopify's jobs run. When everything is removed, the discount is read once more to check; codes still there are retried. Batches start at 250 codes and drop to 100 if Shopify rejects them. Never removes all codes of a discount, and `keepCsvPath` is refused if none of its codes is on the discount. Note: `keepCsvPath` also removes the discount's own main code unless it is in the list; afterwards the discount can no longer be found by that code, only by its ID or a remaining code
583
- - Inputs:
584
- - `discount` (string, required): GID, admin URL number or a code
585
- - `codes` / `removeCsvPath` / `keepCsvPath`: exactly one of them
586
- - `outputDir` (string, required): Folder for the run files (local mode only)
587
- - `runName` (string, optional): Name of the run files. The same name continues the run, a new name starts a new one
588
- - `dryRun` (boolean, default `true`): Build and show the plan, remove nothing
589
- - `confirmCount` (number): Required on the first `dryRun=false` call of a run: the count from the dry run. Not needed when continuing
590
- - `maxSeconds` (number, default 50): Time budget per call
591
-
592
- ### Translation Management (4 tools)
593
-
594
- Requires the `read_locales`, `read_translations` and `write_translations` scopes. Translations are written directly to the live store; there is no review step and no exclusion rules or glossary are applied.
595
-
596
- 1. **`get-shop-locales`**
597
-
598
- - Get the shop's enabled locales, including the primary locale and which are published
599
- - Inputs:
600
- - `published` (boolean, optional): Only return published locales
601
-
602
- 2. **`get-translatable-resources`**
603
-
604
- - Read translatable fields and existing translations for one locale. Each field returns its source value, digest, current translation and `outdated` flag
605
- - Inputs:
606
- - `locale` (string, required): Target locale, e.g. `"en"`
607
- - `resourceIds` (array of strings, optional): GIDs of specific resources (max 50). Takes precedence over `resourceType`
608
- - `resourceType` (string, optional): `TranslatableResourceType` to list, e.g. `"PRODUCT"`, `"PAGE"`, `"ONLINE_STORE_THEME"`
609
- - `marketId` (string, optional): Market GID for market-specific translations
610
- - `keys` (array of strings, optional): Only return these field keys
611
- - `onlyMissingOrOutdated` (boolean, optional): Only return untranslated or outdated fields
612
- - `first` (number, default: 10): Number of resources when listing by type (max 50)
613
- - `after` (string, optional): Pagination cursor
614
-
615
- 3. **`register-translations`**
616
-
617
- - Create or update translations on a single resource. Missing digests are fetched automatically
618
- - Inputs:
619
- - `resourceId` (string, required): GID of the resource
620
- - `translations` (array, required): Up to 100 items, each with `key`, `locale`, `value`, and optional `translatableContentDigest`, `marketId`
621
-
622
- 4. **`remove-translations`**
623
-
624
- - Delete translations for the given keys and locales on a single resource
625
- - Inputs:
626
- - `resourceId` (string, required): GID of the resource
627
- - `translationKeys` (array of strings, required): Field keys to remove
628
- - `locales` (array of strings, required): Locales to remove from
629
- - `marketIds` (array of strings, optional): Market GIDs for market-specific translations
630
-
631
- ### Metaobject & File Management (6 tools)
632
-
633
- Requires the `read_metaobject_definitions`, `read_metaobjects`, `write_metaobjects`, `read_files` and `write_files` scopes.
634
-
635
- 1. **`get-metaobject-definitions`**
636
-
637
- - Get all metaobject definitions (types) with field keys, field types, required flags, validations and whether Active/Draft status is enabled
638
- - Inputs:
639
- - `first` (number, default: 25): Number of definitions to return (max 50)
640
- - `after` (string, optional): Pagination cursor
641
-
642
- 2. **`get-metaobjects`**
643
-
644
- - Get metaobject entries of one type with handle, display name, field values and Active/Draft status
645
- - Inputs:
646
- - `type` (string, required): Metaobject definition type, e.g. `"shipping_bar_settings"`
647
- - `first` (number, default: 25): Number of entries to return (max 50)
648
- - `after` (string, optional): Pagination cursor
649
-
650
- 3. **`upsert-metaobject`**
651
-
652
- - Create or update a metaobject entry by type and handle
653
- - Inputs:
654
- - `type` (string, required): Metaobject definition type
655
- - `handle` (string, required): Entry handle. Updates the entry if it exists, otherwise creates it
656
- - `fields` (array, required): Items with `key` and `value`. Values are strings: lists as JSON arrays, references as GIDs, rich text as Shopify rich text JSON, dates as ISO 8601
657
- - `status` (string, optional): `"ACTIVE"` or `"DRAFT"`, for types with Active/Draft status enabled
658
-
659
- 4. **`delete-metaobject`**
660
-
661
- - Permanently delete a metaobject entry
662
- - Inputs:
663
- - `id` (string, required): Metaobject GID
664
-
665
- 5. **`get-files`**
666
-
667
- - Search files in Content > Files, newest first. Returns GIDs for use in file reference fields
668
- - Inputs:
669
- - `query` (string, optional): Search query, e.g. `"filename:hero*"`, `"media_type:IMAGE"`
670
- - `first` (number, default: 25): Number of files to return (max 50)
671
- - `after` (string, optional): Pagination cursor
672
-
673
- 6. **`create-files`**
674
-
675
- - Upload files to Content > Files from a public URL or a local file path. Files are processed asynchronously; check `fileStatus` with `get-files`
676
- - Inputs:
677
- - `files` (array, required): Up to 25 items, each with exactly one of `originalSource` (public URL) or `filePath` (local path, stdio mode only; jpg, jpeg, png, gif, webp, svg, mp4, mov, webm, pdf), plus optional `alt`, `filename`, `contentType` (`"IMAGE"`, `"VIDEO"`, `"FILE"`)
678
-
679
- ### Order Query Filter Reference
680
-
681
- The `get-orders` tool's `query` parameter supports [Shopify search syntax](https://shopify.dev/docs/api/usage/search-syntax):
682
-
683
- | Filter | Example |
684
- |--------|---------|
685
- | `name` | `name:#77235` |
686
- | `created_at` | `created_at:>2024-01-01` or `created_at:2024-01-01..2024-03-31` |
687
- | `updated_at` | `updated_at:>2024-06-01` |
688
- | `financial_status` | `financial_status:paid` |
689
- | `fulfillment_status` | `fulfillment_status:shipped` |
690
- | `status` | `status:open` |
691
- | `email` | `email:customer@example.com` |
692
- | `tag` / `tag_not` | `tag:vip tag_not:wholesale` |
693
- | `discount_code` | `discount_code:SUMMER20` |
694
- | `sku` | `sku:PROD-001` |
695
- | `risk_level` | `risk_level:high` |
696
- | `gateway` | `gateway:shopify_payments` |
697
- | `test` | `test:true` |
698
-
699
- ## Debugging
700
-
701
- If you encounter issues, check Claude Desktop's MCP logs:
702
-
703
- ```
704
- tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
705
- ```
706
-
707
- ## License
708
-
709
- MIT
1
+ # Shopify MCP Server (Yoffi Digital fork)
2
+
3
+ MCP Server for the Shopify Admin API, enabling interaction with store data through GraphQL. This server provides tools for managing products, customers, orders, discounts, and more.
4
+
5
+ This is a fork of [shopify-mcp](https://github.com/GeLi2001/shopify-mcp) by GeLi2001, extended by [Yoffi Digital](https://github.com/yoffi-digital) with discount-management tools (`create-discount`, `create-automatic-discount`) and other fixes.
6
+
7
+ ## Features
8
+
9
+ - **Product Management**: Full CRUD for products, variants, and options (8 tools)
10
+ - **Customer Management**: Full CRUD, merge, and address management (8 tools)
11
+ - **Order Management**: Smart lookup, cancel, close/open, mark as paid, fulfillment, refunds (10 tools)
12
+ - **Metafield Management**: Get, set, and delete metafields on any resource (3 tools)
13
+ - **Inventory Management**: Set absolute inventory quantities at locations (1 tool)
14
+ - **Tag Management**: Add/remove tags on any taggable resource (1 tool)
15
+ - **Discount Management**: Create percentage or fixed-amount discount codes, store-wide or scoped to collections, bulk-attach thousands of codes to an existing discount, pause/reschedule/delete discounts, export or remove codes (7 tools)
16
+ - **Translation Management**: List shop locales, read translatable content, and register or remove translations (4 tools)
17
+ - **Metaobject & File Management**: Read definitions, list/create/update/delete metaobject entries, search and upload files (6 tools)
18
+ - **Pagination & Sorting**: Cursor-based pagination and sort keys on all list queries
19
+ - **Advanced Filtering**: Pass-through Shopify query syntax for all list endpoints
20
+ - **GraphQL Integration**: Direct integration with Shopify's GraphQL Admin API (2026-07)
21
+ - **Comprehensive Error Handling**: Clear error messages for API and authentication issues
22
+
23
+ ## Prerequisites
24
+
25
+ 1. Node.js (version 18 or higher)
26
+ 2. A Shopify store with a custom app (see setup instructions below)
27
+
28
+ ## Setup
29
+
30
+ ### Authentication
31
+
32
+ This server supports two authentication methods:
33
+
34
+ #### Option 1: Client Credentials (Dev Dashboard apps, January 2026+)
35
+
36
+ As of January 1, 2026, new Shopify apps are created in the **Dev Dashboard** and use OAuth client credentials instead of static access tokens.
37
+
38
+ 1. From your Shopify admin, go to **Settings** > **Apps and sales channels**
39
+ 2. Click **Develop apps** > **Build app in dev dashboard**
40
+ 3. Create a new app and configure **Admin API scopes**:
41
+ - `read_products`, `write_products`
42
+ - `read_customers`, `write_customers`
43
+ - `read_orders`, `write_orders`
44
+ - `read_locales`, `read_translations`, `write_translations` (for the translation tools)
45
+ - `read_metaobject_definitions`, `read_metaobjects`, `write_metaobjects`, `read_files`, `write_files` (for the metaobject and file tools)
46
+ 4. Install the app on your store
47
+ 5. Copy your **Client ID** and **Client Secret** from the app's API credentials
48
+
49
+ The server will automatically exchange these for an access token and refresh it before it expires (tokens are valid for ~24 hours).
50
+
51
+ #### Option 2: Static Access Token (legacy apps)
52
+
53
+ If you have an existing custom app with a static `shpat_` access token, you can still use it directly.
54
+
55
+ This package is not currently published to npm — clone the repo and build it locally:
56
+
57
+ ```bash
58
+ git clone https://github.com/yoffi-digital/mcp-shopify-yoffi.git
59
+ cd mcp-shopify-yoffi
60
+ npm install
61
+ npm run build
62
+ ```
63
+
64
+ This produces `dist/index.js`, which the commands below reference directly.
65
+
66
+ ### Usage with Claude Desktop
67
+
68
+ **Client Credentials (recommended):**
69
+
70
+ ```json
71
+ {
72
+ "mcpServers": {
73
+ "shopify": {
74
+ "command": "node",
75
+ "args": [
76
+ "/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
77
+ "--clientId",
78
+ "<YOUR_CLIENT_ID>",
79
+ "--clientSecret",
80
+ "<YOUR_CLIENT_SECRET>",
81
+ "--domain",
82
+ "<YOUR_SHOP>.myshopify.com"
83
+ ]
84
+ }
85
+ }
86
+ }
87
+ ```
88
+
89
+ **Static Access Token (legacy):**
90
+
91
+ ```json
92
+ {
93
+ "mcpServers": {
94
+ "shopify": {
95
+ "command": "node",
96
+ "args": [
97
+ "/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
98
+ "--accessToken",
99
+ "<YOUR_ACCESS_TOKEN>",
100
+ "--domain",
101
+ "<YOUR_SHOP>.myshopify.com"
102
+ ]
103
+ }
104
+ }
105
+ }
106
+ ```
107
+
108
+ Locations for the Claude Desktop config file:
109
+
110
+ - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
111
+ - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
112
+
113
+ ### Usage with Claude Code
114
+
115
+ **Client Credentials:**
116
+
117
+ ```bash
118
+ claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
119
+ --clientId YOUR_CLIENT_ID \
120
+ --clientSecret YOUR_CLIENT_SECRET \
121
+ --domain your-store.myshopify.com
122
+ ```
123
+
124
+ **Static Access Token (legacy):**
125
+
126
+ ```bash
127
+ claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
128
+ --accessToken YOUR_ACCESS_TOKEN \
129
+ --domain your-store.myshopify.com
130
+ ```
131
+
132
+ ### Alternative: Run Locally with Environment Variables
133
+
134
+ If you prefer to use environment variables instead of command-line arguments:
135
+
136
+ 1. Create a `.env` file with your Shopify credentials:
137
+
138
+ **Client Credentials:**
139
+ ```
140
+ SHOPIFY_CLIENT_ID=your_client_id
141
+ SHOPIFY_CLIENT_SECRET=your_client_secret
142
+ MYSHOPIFY_DOMAIN=your-store.myshopify.com
143
+ ```
144
+
145
+ **Static Access Token (legacy):**
146
+ ```
147
+ SHOPIFY_ACCESS_TOKEN=your_access_token
148
+ MYSHOPIFY_DOMAIN=your-store.myshopify.com
149
+ ```
150
+
151
+ 2. Run the server:
152
+ ```
153
+ node dist/index.js
154
+ ```
155
+
156
+ ### Additional Options
157
+
158
+ - `--apiVersion`: Specify the Shopify API version (default: `2026-07`). Can also be set via `SHOPIFY_API_VERSION` environment variable.
159
+
160
+ ## Available Tools (32)
161
+
162
+ ### Pagination, Sorting & Filtering
163
+
164
+ All list query tools (`get-products`, `get-customers`, `get-orders`, `get-customer-orders`) support:
165
+
166
+ - **Cursor-based pagination**: `after` / `before` (cursor strings), with `pageInfo` in the response (`hasNextPage`, `hasPreviousPage`, `startCursor`, `endCursor`)
167
+ - **Sorting**: `sortKey` (enum specific to each resource) and `reverse` (boolean)
168
+ - **Advanced filtering**: `query` or `searchQuery` parameter accepting [Shopify query syntax](https://shopify.dev/docs/api/usage/search-syntax)
169
+
170
+ ### Product Management (8 tools)
171
+
172
+ 1. **`get-products`**
173
+
174
+ - Get all products or search by title with pagination and sorting
175
+ - Inputs:
176
+ - `searchTitle` (string, optional): Filter products by title (wraps in `title:*...*`)
177
+ - `limit` (number, default: 10): Maximum number of products to return
178
+ - `query` (string, optional): Raw Shopify query string (e.g. `"status:active vendor:Nike tag:sale"`)
179
+ - `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `INVENTORY_TOTAL`, `PRODUCT_TYPE`, `PUBLISHED_AT`, `RELEVANCE`, `TITLE`, `UPDATED_AT`, `VENDOR`
180
+ - `reverse` (boolean, optional): Reverse the sort order
181
+ - `after` / `before` (string, optional): Pagination cursors
182
+
183
+ 2. **`get-product-by-id`**
184
+
185
+ - Get a specific product by ID with full details including SEO, options, media, variants, and collections
186
+ - Inputs:
187
+ - `productId` (string, required): Shopify product GID
188
+ - Returns: `productType`, `descriptionHtml`, `seo`, `options` (with `optionValues`), `media` (images), `variants`, `collections`, `tags`, `vendor`, price range, inventory
189
+
190
+ 3. **`create-product`**
191
+
192
+ - Create a new product. When using `productOptions`, Shopify registers all option values but only creates one default variant (first value of each option, price $0). Use `manage-product-variants` with `strategy: REMOVE_STANDALONE_VARIANT` afterward to create all real variants with prices.
193
+ - Inputs:
194
+ - `title` (string, required): Title of the product
195
+ - `descriptionHtml` (string, optional): Description with HTML
196
+ - `handle` (string, optional): URL slug. Auto-generated from title if omitted
197
+ - `vendor` (string, optional): Vendor of the product
198
+ - `productType` (string, optional): Type of the product
199
+ - `tags` (array of strings, optional): Product tags
200
+ - `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`. Default `"DRAFT"`
201
+ - `seo` (object, optional): `{ title, description }` for search engines
202
+ - `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
203
+ - `productOptions` (array of objects, optional): Options to create inline, e.g. `[{ name: "Size", values: [{ name: "S" }, { name: "M" }] }]`. Max 3 options.
204
+ - `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
205
+
206
+ 4. **`update-product`**
207
+
208
+ - Update an existing product's fields
209
+ - Inputs:
210
+ - `id` (string, required): Shopify product GID
211
+ - `title` (string, optional): New title
212
+ - `descriptionHtml` (string, optional): New description
213
+ - `handle` (string, optional): New URL slug
214
+ - `vendor` (string, optional): New vendor
215
+ - `productType` (string, optional): New product type
216
+ - `tags` (array of strings, optional): New tags (overwrites existing)
217
+ - `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`
218
+ - `seo` (object, optional): `{ title, description }` for search engines
219
+ - `metafields` (array of objects, optional): Metafields to set or update
220
+ - `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
221
+ - `collectionsToLeave` (array of strings, optional): Collection GIDs to remove the product from
222
+ - `redirectNewHandle` (boolean, optional): If true, old handle redirects to new handle
223
+
224
+ 5. **`delete-product`**
225
+
226
+ - Delete a product
227
+ - Inputs:
228
+ - `id` (string, required): Shopify product GID
229
+
230
+ 6. **`manage-product-options`**
231
+
232
+ - Create, update, or delete product options (e.g. Size, Color)
233
+ - Inputs:
234
+ - `productId` (string, required): Shopify product GID
235
+ - `action` (string, required): `"create"`, `"update"`, or `"delete"`
236
+ - `variantStrategy` (string, optional): `"LEAVE_AS_IS"` (default) or `"CREATE"` — controls whether new variant combinations are generated when adding options
237
+ - For `action: "create"`:
238
+ - `options` (array, required): Options to create, e.g. `[{ name: "Size", values: ["S", "M", "L"] }]`
239
+ - For `action: "update"`:
240
+ - `optionId` (string, required): Option GID to update
241
+ - `name` (string, optional): New name for the option
242
+ - `position` (number, optional): New position
243
+ - `valuesToAdd` (array of strings, optional): Values to add
244
+ - `valuesToDelete` (array of strings, optional): Value GIDs to remove
245
+ - For `action: "delete"`:
246
+ - `optionIds` (array of strings, required): Option GIDs to delete
247
+
248
+ 7. **`manage-product-variants`**
249
+
250
+ - Create or update product variants in bulk
251
+ - Inputs:
252
+ - `productId` (string, required): Shopify product GID
253
+ - `strategy` (string, optional): How to handle the default variant when creating. `"DEFAULT"` (removes "Default Title" automatically), `"REMOVE_STANDALONE_VARIANT"` (recommended for full control), or `"PRESERVE_STANDALONE_VARIANT"`
254
+ - `variants` (array, required): Variants to create or update. Each variant:
255
+ - `id` (string, optional): Variant GID for updates. Omit to create new
256
+ - `price` (string, optional): Price, e.g. `"49.00"`
257
+ - `compareAtPrice` (string, optional): Compare-at price for showing discounts
258
+ - `sku` (string, optional): SKU (mapped to `inventoryItem.sku`)
259
+ - `tracked` (boolean, optional): Whether inventory is tracked. Set `false` for print-on-demand
260
+ - `taxable` (boolean, optional): Whether the variant is taxable
261
+ - `barcode` (string, optional): Barcode
262
+ - `weight` (number, optional): Weight of the variant
263
+ - `weightUnit` (string, optional): `"GRAMS"`, `"KILOGRAMS"`, `"OUNCES"`, or `"POUNDS"`
264
+ - `optionValues` (array, optional): Option values, e.g. `[{ optionName: "Size", name: "A4" }]`
265
+
266
+ 8. **`delete-product-variants`**
267
+
268
+ - Delete one or more variants from a product
269
+ - Inputs:
270
+ - `productId` (string, required): Shopify product GID
271
+ - `variantIds` (array of strings, required): Variant GIDs to delete
272
+
273
+ ### Customer Management (8 tools)
274
+
275
+ 1. **`get-customers`**
276
+
277
+ - List customers with search, pagination, and sorting
278
+ - Inputs:
279
+ - `searchQuery` (string, optional): Freetext or Shopify query syntax (e.g. `"country:US tag:vip orders_count:>5"`)
280
+ - `limit` (number, default: 10): Maximum number of customers to return
281
+ - `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `LAST_UPDATE`, `LOCATION`, `NAME`, `ORDERS_COUNT`, `RELEVANCE`, `TOTAL_SPENT`, `UPDATED_AT`
282
+ - `reverse` (boolean, optional): Reverse the sort order
283
+ - `after` / `before` (string, optional): Pagination cursors
284
+
285
+ 2. **`get-customer-by-id`**
286
+
287
+ - Get a single customer by ID with full details
288
+ - Inputs:
289
+ - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
290
+ - Returns: name, email, phone, addresses, tags, note, tax status, amount spent, order count, metafields
291
+
292
+ 3. **`create-customer`**
293
+
294
+ - Create a new customer
295
+ - Inputs:
296
+ - `firstName` (string, optional): Customer's first name
297
+ - `lastName` (string, optional): Customer's last name
298
+ - `email` (string, optional): Customer's email address
299
+ - `phone` (string, optional): Customer's phone number
300
+ - `tags` (array of strings, optional): Tags to apply
301
+ - `note` (string, optional): Note about the customer
302
+ - `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
303
+ - `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
304
+ - `addresses` (array of objects, optional): Customer addresses (`address1`, `address2`, `city`, `provinceCode`, `zip`, `country`, `phone`)
305
+
306
+ 4. **`update-customer`**
307
+
308
+ - Update a customer's information
309
+ - Inputs:
310
+ - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
311
+ - `firstName` (string, optional): Customer's first name
312
+ - `lastName` (string, optional): Customer's last name
313
+ - `email` (string, optional): Customer's email address
314
+ - `phone` (string, optional): Customer's phone number
315
+ - `tags` (array of strings, optional): Tags to apply to the customer
316
+ - `note` (string, optional): Note about the customer
317
+ - `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
318
+ - `emailMarketingConsent` (object, optional): Email marketing consent settings
319
+ - `marketingState` (string, required): `"NOT_SUBSCRIBED"`, `"SUBSCRIBED"`, `"UNSUBSCRIBED"`, or `"PENDING"`
320
+ - `consentUpdatedAt` (string, optional): ISO 8601 timestamp
321
+ - `marketingOptInLevel` (string, optional): `"SINGLE_OPT_IN"`, `"CONFIRMED_OPT_IN"`, or `"UNKNOWN"`
322
+ - `metafields` (array of objects, optional): Customer metafields
323
+
324
+ 5. **`delete-customer`**
325
+
326
+ - Delete a customer
327
+ - Inputs:
328
+ - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
329
+
330
+ 6. **`customer-merge`**
331
+
332
+ - Merge two customer records into one
333
+ - Inputs:
334
+ - `customerOneId` (string, required): GID of the first customer
335
+ - `customerTwoId` (string, required): GID of the second customer
336
+ - `overrideFields` (object, optional): Override which fields to keep from which customer (firstName, lastName, email, phone, defaultAddress, note, tags)
337
+
338
+ 7. **`manage-customer-address`**
339
+
340
+ - Create, update, or delete a customer's mailing address
341
+ - Inputs:
342
+ - `customerId` (string, required): Customer GID
343
+ - `action` (string, required): `"create"`, `"update"`, or `"delete"`
344
+ - `addressId` (string, optional): Address GID (required for update/delete)
345
+ - `address` (object, optional): Address fields (required for create/update): `address1`, `address2`, `city`, `company`, `countryCode`, `firstName`, `lastName`, `phone`, `provinceCode`, `zip`
346
+ - `setAsDefault` (boolean, optional): Set as customer's default address
347
+
348
+ ### Order Management (10 tools)
349
+
350
+ 1. **`get-orders`**
351
+
352
+ - Get orders with filtering, pagination, and sorting
353
+ - Inputs:
354
+ - `status` (string, optional): `"any"`, `"open"`, `"closed"`, or `"cancelled"`. Default `"any"`
355
+ - `limit` (number, default: 10): Maximum number of orders to return
356
+ - `query` (string, optional): Raw Shopify query string (e.g. `"financial_status:paid fulfillment_status:shipped tag:rush"`)
357
+ - `sortKey` (string, optional): One of `CREATED_AT`, `ORDER_NUMBER`, `TOTAL_PRICE`, `FINANCIAL_STATUS`, `FULFILLMENT_STATUS`, `UPDATED_AT`, `CUSTOMER_NAME`, `PROCESSED_AT`, `ID`, `RELEVANCE`
358
+ - `reverse` (boolean, optional): Reverse the sort order
359
+ - `after` / `before` (string, optional): Pagination cursors
360
+
361
+ 2. **`get-order-by-id`**
362
+
363
+ - Get a specific order by ID with smart lookup — accepts order name (`#77235` or `77235`), numeric ID (`8054938337547`), or full GID (`gid://shopify/Order/...`)
364
+ - Inputs:
365
+ - `orderId` (string, required): Order name, numeric ID, or full GID
366
+ - Returns: pricing, customer, shipping/billing addresses, line items, tags, notes, metafields, cancel reason, return status, discount codes, PO number, timestamps
367
+
368
+ 3. **`update-order`**
369
+
370
+ - Update an existing order
371
+ - Inputs:
372
+ - `id` (string, required): Shopify order GID
373
+ - `tags` (array of strings, optional): New tags for the order
374
+ - `email` (string, optional): Update customer email on the order
375
+ - `note` (string, optional): Order notes
376
+ - `phone` (string, optional): Phone number for the order
377
+ - `poNumber` (string, optional): Purchase order number
378
+ - `customAttributes` (array of objects, optional): Custom key-value attributes
379
+ - `metafields` (array of objects, optional): Order metafields
380
+ - `shippingAddress` (object, optional): Shipping address fields
381
+
382
+ 4. **`get-customer-orders`**
383
+
384
+ - Get orders for a specific customer with pagination and sorting
385
+ - Inputs:
386
+ - `customerId` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
387
+ - `limit` (number, default: 10): Maximum number of orders to return
388
+ - `sortKey` (string, optional): Same sort keys as `get-orders`
389
+ - `reverse` (boolean, optional): Reverse the sort order
390
+ - `after` / `before` (string, optional): Pagination cursors
391
+
392
+ 5. **`order-cancel`**
393
+
394
+ - Cancel an order with options for refunding, restocking, and customer notification. **Irreversible.**
395
+ - Inputs:
396
+ - `orderId` (string, required): Order GID
397
+ - `reason` (string, required): `"CUSTOMER"`, `"DECLINED"`, `"FRAUD"`, `"INVENTORY"`, `"OTHER"`, or `"STAFF"`
398
+ - `restock` (boolean, required): Whether to restock inventory
399
+ - `notifyCustomer` (boolean, default: false): Notify the customer
400
+ - `staffNote` (string, optional): Internal note
401
+ - `refund` (boolean, optional): Refund to original payment method
402
+
403
+ 6. **`order-close-open`**
404
+
405
+ - Close or reopen an order
406
+ - Inputs:
407
+ - `orderId` (string, required): Order GID
408
+ - `action` (string, required): `"close"` or `"open"`
409
+
410
+ 7. **`order-mark-as-paid`**
411
+
412
+ - Mark an order as paid (for manual/offline payments)
413
+ - Inputs:
414
+ - `orderId` (string, required): Order GID
415
+
416
+ 8. **`create-fulfillment`**
417
+
418
+ - Create a fulfillment (mark items as shipped) with optional tracking
419
+ - Inputs:
420
+ - `lineItemsByFulfillmentOrder` (array, required): Fulfillment orders and line items to fulfill
421
+ - `trackingInfo` (object, optional): `{ number, url, company }` tracking details
422
+ - `notifyCustomer` (boolean, default: false): Send shipping notification
423
+
424
+ 9. **`refund-create`**
425
+
426
+ - Create a full or partial refund with optional restocking
427
+ - Inputs:
428
+ - `orderId` (string, required): Order GID
429
+ - `refundLineItems` (array, optional): Line items to refund with `lineItemId`, `quantity`, `restockType` (`CANCEL`/`RETURN`/`NO_RESTOCK`), `locationId`
430
+ - `shipping` (object, optional): `{ amount, fullRefund }` shipping refund
431
+ - `note` (string, optional): Refund note
432
+ - `notify` (boolean, optional): Send refund notification
433
+
434
+ 10. **`create-draft-order`**
435
+
436
+ - Create a draft order for phone/chat sales, invoicing, or wholesale
437
+ - Inputs:
438
+ - `lineItems` (array, required): Product variants (`variantId`) or custom items (`title` + price). Max 499
439
+ - `customerId` (string, optional): Customer GID
440
+ - `email`, `phone`, `note`, `tags`, `poNumber` (optional)
441
+ - `shippingAddress`, `billingAddress` (objects, optional)
442
+ - `appliedDiscount` (object, optional): `{ title, value, valueType }` order-level discount
443
+
444
+ ### Draft Order Management (1 tool)
445
+
446
+ 1. **`complete-draft-order`**
447
+
448
+ - Complete a draft order, converting it into a real order
449
+ - Inputs:
450
+ - `draftOrderId` (string, required): Draft order GID
451
+ - `paymentGatewayId` (string, optional): Payment gateway GID
452
+
453
+ ### Metafield Management (3 tools)
454
+
455
+ 1. **`get-metafields`**
456
+
457
+ - Get metafields for any Shopify resource (products, orders, customers, variants, collections, etc.)
458
+ - Inputs:
459
+ - `ownerId` (string, required): GID of any resource
460
+ - `namespace` (string, optional): Filter by namespace
461
+ - `first` (number, default: 25): Number of metafields to return
462
+ - `after` (string, optional): Pagination cursor
463
+
464
+ 2. **`set-metafields`**
465
+
466
+ - Set metafields on any Shopify resource. Creates or updates up to 25 metafields atomically
467
+ - Inputs:
468
+ - `metafields` (array, required): Metafields to set, each with `ownerId`, `key`, `value`, and optional `namespace`, `type`
469
+
470
+ 3. **`delete-metafields`**
471
+
472
+ - Delete metafields from any Shopify resource
473
+ - Inputs:
474
+ - `metafields` (array, required): Metafields to delete, each with `ownerId`, `namespace`, `key`
475
+
476
+ ### Inventory Management (1 tool)
477
+
478
+ 1. **`inventory-set-quantities`**
479
+
480
+ - Set absolute inventory quantities for items at specific locations
481
+ - Inputs:
482
+ - `reason` (string, required): Reason for change (e.g. `"correction"`, `"cycle_count_available"`)
483
+ - `name` (string, required): `"available"` or `"on_hand"`
484
+ - `quantities` (array, required): Items with `inventoryItemId`, `locationId`, `quantity`
485
+
486
+ ### Tag Management (1 tool)
487
+
488
+ 1. **`manage-tags`**
489
+
490
+ - Add or remove tags on any taggable resource (orders, products, customers, draft orders, articles)
491
+ - Inputs:
492
+ - `id` (string, required): GID of the resource
493
+ - `tags` (array of strings, required): Tags to add or remove
494
+ - `action` (string, required): `"add"` or `"remove"`
495
+
496
+ ### Discount Management (7 tools)
497
+
498
+ Bulk and maintenance tools (3–7) need the `read_discounts` and `write_discounts` scopes.
499
+
500
+ **Finding a discount:** every tool accepts the discount GID, the number from the admin URL (`/discounts/2269857186117`) or any code that is on it. Searching by code only works while that code is still on the discount. If a code was removed (for example the discount's own main code, which `remove-discount-codes` with `keepCsvPath` removes together with every other code not in the list), use the ID from the admin URL or one of the codes that are still on it.
501
+
502
+ 1. **`create-discount`**
503
+
504
+ - Create a basic discount code (percentage or fixed amount), applied store-wide or scoped to specific collections and/or products
505
+ - Inputs:
506
+ - `title` (string, required): Internal title for the discount
507
+ - `code` (string, required): The discount code customers enter at checkout
508
+ - `valueType` (string, required): `"PERCENTAGE"` or `"FIXED_AMOUNT"`
509
+ - `value` (number, required): Decimal between 0 and 1 for `PERCENTAGE` (e.g. `0.15` for 15%), or the currency amount for `FIXED_AMOUNT`
510
+ - `startsAt` (string, required): ISO 8601 datetime the discount becomes active
511
+ - `endsAt` (string, optional): ISO 8601 datetime the discount expires
512
+ - `appliesOncePerCustomer` (boolean, optional): Limit each customer to a single use
513
+ - `usageLimit` (number, optional): Total number of redemptions allowed
514
+ - `includeCollectionIds` (array of strings, optional): Collection GIDs to scope the discount to (mutually exclusive with the product ID fields)
515
+ - `excludeCollectionIds` (array of strings, optional): Collection GIDs to exclude from an otherwise store-wide discount
516
+ - `includeProductIds` (array of strings, optional): Product GIDs to scope the discount to (mutually exclusive with the collection ID fields)
517
+ - `excludeProductIds` (array of strings, optional): Product GIDs to exclude from an otherwise store-wide discount
518
+ - `combinesWith` (object, optional): `{ productDiscounts, orderDiscounts, shippingDiscounts }` combination rules
519
+
520
+ 2. **`create-automatic-discount`**
521
+
522
+ - Create an automatic discount (percentage or fixed amount) that applies at checkout with no code required, store-wide or scoped to specific collections and/or products
523
+ - Inputs:
524
+ - `title` (string, required): Title for the discount, shown to customers at checkout
525
+ - `valueType` (string, required): `"PERCENTAGE"` or `"FIXED_AMOUNT"`
526
+ - `value` (number, required): Decimal between 0 and 1 for `PERCENTAGE` (e.g. `0.15` for 15%), or the currency amount for `FIXED_AMOUNT`
527
+ - `startsAt` (string, required): ISO 8601 datetime the discount becomes active
528
+ - `endsAt` (string, optional): ISO 8601 datetime the discount expires
529
+ - `minimumSubtotal` (number, optional): Minimum order subtotal required for the discount to apply
530
+ - `includeCollectionIds` (array of strings, optional): Collection GIDs to scope the discount to (mutually exclusive with the product ID fields)
531
+ - `excludeCollectionIds` (array of strings, optional): Collection GIDs to exclude from an otherwise store-wide discount
532
+ - `includeProductIds` (array of strings, optional): Product GIDs to scope the discount to (mutually exclusive with the collection ID fields)
533
+ - `excludeProductIds` (array of strings, optional): Product GIDs to exclude from an otherwise store-wide discount
534
+ - `combinesWith` (object, optional): `{ productDiscounts, orderDiscounts, shippingDiscounts }` combination rules
535
+
536
+ 3. **`add-discount-codes`**
537
+
538
+ - Attach many single-use codes (up to 100,000) to an existing code discount, including app discounts (e.g. SMART). Uploads in batches of 250 and writes two files: `<run>-result.csv` (every code with its status) and `<run>-partner.csv` (only usable codes). Only counts and samples are returned to the chat, never the full code list. Local (stdio) mode only.
539
+ - Statuses: `attached`, `skipped` (already on this discount), `conflict` (on another discount), `failed` (with Shopify's reason)
540
+ - Safe to repeat: each call stops after `maxSeconds`; calling again with the same input resumes from the result file and never uploads a code twice
541
+ - Inputs:
542
+ - `discount` (string, required): Discount GID, the number from the admin URL (`/discounts/123`), or a code already on the discount
543
+ - `generate` (object, optional): `{ count, prefix, length }`, e.g. `{ count: 25000, prefix: "DB-" }`. Uses readable characters only (no 0/O, 1/I/L)
544
+ - `csvPath` (string, optional): Partner CSV with its own codes (`code` column or first column, comma or semicolon). Use this or `generate`
545
+ - `outputDir` (string, optional): Folder for the result files. Required with `generate`; defaults to the CSV's folder
546
+ - `runName` (string, optional): Name of the result files. A new name starts a new run
547
+ - `dryRun` (boolean, default `true`): Show the discount details, plan and warnings without uploading. Reads the discount's current codes, so codes already on it are reported as `alreadyOnDiscount`, not as "would upload"
548
+ - `verify` (boolean, default `false`): Code-by-code reconciliation. Pages through all codes on the discount and compares them with the CSV / result file: `ok`, `missing` (in list, not on discount) and `extra` (on discount, not in list). Writes `<run>-verify.csv` and sets missing codes back to pending, so the next run uploads exactly those. Uploads nothing
549
+ - `maxSeconds` (number, default 50): Time budget per call
550
+ - Resilience: throttled requests are retried (about 47 s), network problems and requests without an answer after 25 s are retried 5 times. If it still fails, the call returns the counts plus `interrupted` instead of an error; calling again continues. `<run>-partner.csv` is written once, when the run is finished. If Windows locks a file (virus scanner, preview), the write is retried and otherwise reported in `fileWarnings` without aborting the call
551
+
552
+ 4. **`manage-discount`**
553
+
554
+ - Pause (`deactivate`), reactivate (`activate`) or reschedule (change start/end date) an existing code discount. Codes are kept. Returns the discount before and after
555
+ - **Native Shopify discounts:** all three actions work.
556
+ - **App discounts (e.g. SMART):** Shopify only lets the app that owns a discount change it, so this tool can do just two things with them: **add codes** (`add-discount-codes`) and **pause** (`deactivate`). `activate` and `reschedule` are refused with a clear message. Activate the discount manually in the Shopify admin, and change its dates in the owning app (SMART)
557
+ - Inputs:
558
+ - `discount` (string, required): Discount GID, the number from the admin URL, or one of its codes
559
+ - `action` (string, required): `"activate"`, `"deactivate"` or `"reschedule"`
560
+ - `startsAt` (string, optional): `reschedule` only, new start (ISO 8601)
561
+ - `endsAt` (string or null, optional): `reschedule` only, new end (ISO 8601); `null` removes the end date
562
+
563
+ 5. **`delete-discounts`**
564
+
565
+ - Permanently delete code discounts including all their codes (e.g. test discounts). Explicit discounts only, never by search. Default `dryRun=true` lists what would be deleted. Discounts already used in orders are skipped unless `allowUsed=true`. Discounts that are not found are reported, so repeating a call is safe
566
+ - Inputs:
567
+ - `discounts` (array of strings, required, max 50): GID, admin URL number or a code of each discount
568
+ - `dryRun` (boolean, default `true`): Only show what would be deleted
569
+ - `confirmCount` (number): Required when `dryRun=false`: the number of discounts that would be deleted (`wouldDelete` from the dry run). A wrong or missing number refuses the deletion
570
+ - `allowUsed` (boolean, default `false`): Also delete discounts that were used in orders
571
+ - `maxSeconds` (number, default 50): How long to wait for Shopify's delete job
572
+
573
+ 6. **`get-discount-codes`**
574
+
575
+ - Look up a discount by ID, admin URL number or any of its codes (which discount does this code belong to?) and show its details. With `outputDir` it exports all codes to `<run>-codes.csv`; large discounts (25,000+) take several calls, repeat the same input to continue. The chat only gets details, counts and sample codes
576
+ - Inputs:
577
+ - `discount` (string, required): GID, admin URL number or a code
578
+ - `outputDir` (string, optional): Folder for the CSV export (local mode only)
579
+ - `runName` (string, optional): Name of the export files
580
+ - `maxSeconds` (number, default 50): Time budget per call
581
+
582
+ 7. **`remove-discount-codes`**
583
+
584
+ - Remove codes from a discount without deleting it, e.g. extra codes after an upload. Three modes: `codes` (explicit list), `removeCsvPath` (codes to remove) or `keepCsvPath` (codes that must stay, everything else is removed). Default `dryRun=true` reads the discount once, builds the plan and writes `<run>-remove-plan.csv` (code + status) and a state file `<run>-remove-state.json`. The first real run needs `confirmCount` equal to the planned count; after that the run is confirmed. Large removals (25,000 codes) continue over several calls: repeat the same input (same `runName`, no `confirmCount`); each call works through the saved plan without re-reading the discount, so it is not affected by the count changing while Shopify's jobs run. When everything is removed, the discount is read once more to check; codes still there are retried. Batches start at 250 codes and drop to 100 if Shopify rejects them. Never removes all codes of a discount, and `keepCsvPath` is refused if none of its codes is on the discount. Note: `keepCsvPath` also removes the discount's own main code unless it is in the list; afterwards the discount can no longer be found by that code, only by its ID or a remaining code
585
+ - Inputs:
586
+ - `discount` (string, required): GID, admin URL number or a code
587
+ - `codes` / `removeCsvPath` / `keepCsvPath`: exactly one of them
588
+ - `outputDir` (string, required): Folder for the run files (local mode only)
589
+ - `runName` (string, optional): Name of the run files. The same name continues the run, a new name starts a new one
590
+ - `dryRun` (boolean, default `true`): Build and show the plan, remove nothing
591
+ - `confirmCount` (number): Required on the first `dryRun=false` call of a run: the count from the dry run. Not needed when continuing
592
+ - `maxSeconds` (number, default 50): Time budget per call
593
+
594
+ ### Translation Management (4 tools)
595
+
596
+ Requires the `read_locales`, `read_translations` and `write_translations` scopes. Translations are written directly to the live store; there is no review step and no exclusion rules or glossary are applied.
597
+
598
+ 1. **`get-shop-locales`**
599
+
600
+ - Get the shop's enabled locales, including the primary locale and which are published
601
+ - Inputs:
602
+ - `published` (boolean, optional): Only return published locales
603
+
604
+ 2. **`get-translatable-resources`**
605
+
606
+ - Read translatable fields and existing translations for one locale. Each field returns its source value, digest, current translation and `outdated` flag
607
+ - Inputs:
608
+ - `locale` (string, required): Target locale, e.g. `"en"`
609
+ - `resourceIds` (array of strings, optional): GIDs of specific resources (max 50). Takes precedence over `resourceType`
610
+ - `resourceType` (string, optional): `TranslatableResourceType` to list, e.g. `"PRODUCT"`, `"PAGE"`, `"ONLINE_STORE_THEME"`
611
+ - `marketId` (string, optional): Market GID for market-specific translations
612
+ - `keys` (array of strings, optional): Only return these field keys
613
+ - `onlyMissingOrOutdated` (boolean, optional): Only return untranslated or outdated fields
614
+ - `first` (number, default: 10): Number of resources when listing by type (max 50)
615
+ - `after` (string, optional): Pagination cursor
616
+
617
+ 3. **`register-translations`**
618
+
619
+ - Create or update translations on a single resource. Missing digests are fetched automatically
620
+ - Inputs:
621
+ - `resourceId` (string, required): GID of the resource
622
+ - `translations` (array, required): Up to 100 items, each with `key`, `locale`, `value`, and optional `translatableContentDigest`, `marketId`
623
+
624
+ 4. **`remove-translations`**
625
+
626
+ - Delete translations for the given keys and locales on a single resource
627
+ - Inputs:
628
+ - `resourceId` (string, required): GID of the resource
629
+ - `translationKeys` (array of strings, required): Field keys to remove
630
+ - `locales` (array of strings, required): Locales to remove from
631
+ - `marketIds` (array of strings, optional): Market GIDs for market-specific translations
632
+
633
+ ### Metaobject & File Management (6 tools)
634
+
635
+ Requires the `read_metaobject_definitions`, `read_metaobjects`, `write_metaobjects`, `read_files` and `write_files` scopes.
636
+
637
+ 1. **`get-metaobject-definitions`**
638
+
639
+ - Get all metaobject definitions (types) with field keys, field types, required flags, validations and whether Active/Draft status is enabled
640
+ - Inputs:
641
+ - `first` (number, default: 25): Number of definitions to return (max 50)
642
+ - `after` (string, optional): Pagination cursor
643
+
644
+ 2. **`get-metaobjects`**
645
+
646
+ - Get metaobject entries of one type with handle, display name, field values and Active/Draft status
647
+ - Inputs:
648
+ - `type` (string, required): Metaobject definition type, e.g. `"shipping_bar_settings"`
649
+ - `first` (number, default: 25): Number of entries to return (max 50)
650
+ - `after` (string, optional): Pagination cursor
651
+
652
+ 3. **`upsert-metaobject`**
653
+
654
+ - Create or update a metaobject entry by type and handle
655
+ - Inputs:
656
+ - `type` (string, required): Metaobject definition type
657
+ - `handle` (string, required): Entry handle. Updates the entry if it exists, otherwise creates it
658
+ - `fields` (array, required): Items with `key` and `value`. Values are strings: lists as JSON arrays, references as GIDs, rich text as Shopify rich text JSON, dates as ISO 8601
659
+ - `status` (string, optional): `"ACTIVE"` or `"DRAFT"`, for types with Active/Draft status enabled
660
+
661
+ 4. **`delete-metaobject`**
662
+
663
+ - Permanently delete a metaobject entry
664
+ - Inputs:
665
+ - `id` (string, required): Metaobject GID
666
+
667
+ 5. **`get-files`**
668
+
669
+ - Search files in Content > Files, newest first. Returns GIDs for use in file reference fields
670
+ - Inputs:
671
+ - `query` (string, optional): Search query, e.g. `"filename:hero*"`, `"media_type:IMAGE"`
672
+ - `first` (number, default: 25): Number of files to return (max 50)
673
+ - `after` (string, optional): Pagination cursor
674
+
675
+ 6. **`create-files`**
676
+
677
+ - Upload files to Content > Files from a public URL or a local file path. Files are processed asynchronously; check `fileStatus` with `get-files`
678
+ - Inputs:
679
+ - `files` (array, required): Up to 25 items, each with exactly one of `originalSource` (public URL) or `filePath` (local path, stdio mode only; jpg, jpeg, png, gif, webp, svg, mp4, mov, webm, pdf), plus optional `alt`, `filename`, `contentType` (`"IMAGE"`, `"VIDEO"`, `"FILE"`)
680
+
681
+ ### Order Query Filter Reference
682
+
683
+ The `get-orders` tool's `query` parameter supports [Shopify search syntax](https://shopify.dev/docs/api/usage/search-syntax):
684
+
685
+ | Filter | Example |
686
+ |--------|---------|
687
+ | `name` | `name:#77235` |
688
+ | `created_at` | `created_at:>2024-01-01` or `created_at:2024-01-01..2024-03-31` |
689
+ | `updated_at` | `updated_at:>2024-06-01` |
690
+ | `financial_status` | `financial_status:paid` |
691
+ | `fulfillment_status` | `fulfillment_status:shipped` |
692
+ | `status` | `status:open` |
693
+ | `email` | `email:customer@example.com` |
694
+ | `tag` / `tag_not` | `tag:vip tag_not:wholesale` |
695
+ | `discount_code` | `discount_code:SUMMER20` |
696
+ | `sku` | `sku:PROD-001` |
697
+ | `risk_level` | `risk_level:high` |
698
+ | `gateway` | `gateway:shopify_payments` |
699
+ | `test` | `test:true` |
700
+
701
+ ## Debugging
702
+
703
+ If you encounter issues, check Claude Desktop's MCP logs:
704
+
705
+ ```
706
+ tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
707
+ ```
708
+
709
+ ## License
710
+
711
+ MIT