mcp-shopify-yoffi 1.0.8

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.
Files changed (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +558 -0
  3. package/dist/index.js +91 -0
  4. package/dist/lib/formatters.js +72 -0
  5. package/dist/lib/shopifyAuth.js +93 -0
  6. package/dist/lib/toolUtils.js +36 -0
  7. package/dist/tools/completeDraftOrder.js +76 -0
  8. package/dist/tools/createAutomaticDiscount.js +149 -0
  9. package/dist/tools/createCustomer.js +142 -0
  10. package/dist/tools/createDiscount.js +177 -0
  11. package/dist/tools/createDraftOrder.js +160 -0
  12. package/dist/tools/createFulfillment.js +100 -0
  13. package/dist/tools/createProduct.js +123 -0
  14. package/dist/tools/createRefund.js +115 -0
  15. package/dist/tools/deleteCustomer.js +47 -0
  16. package/dist/tools/deleteMetafields.js +54 -0
  17. package/dist/tools/deleteProduct.js +43 -0
  18. package/dist/tools/deleteProductVariants.js +82 -0
  19. package/dist/tools/getCollectionById.js +123 -0
  20. package/dist/tools/getCollections.js +88 -0
  21. package/dist/tools/getCustomerById.js +122 -0
  22. package/dist/tools/getCustomerOrders.js +131 -0
  23. package/dist/tools/getCustomers.js +125 -0
  24. package/dist/tools/getFulfillmentOrders.js +106 -0
  25. package/dist/tools/getInventoryItems.js +86 -0
  26. package/dist/tools/getInventoryLevels.js +82 -0
  27. package/dist/tools/getLocations.js +85 -0
  28. package/dist/tools/getMarkets.js +91 -0
  29. package/dist/tools/getMetafieldDefinitions.js +112 -0
  30. package/dist/tools/getMetafields.js +68 -0
  31. package/dist/tools/getOrderById.js +212 -0
  32. package/dist/tools/getOrderRefundDetails.js +131 -0
  33. package/dist/tools/getOrderTransactions.js +85 -0
  34. package/dist/tools/getOrders.js +148 -0
  35. package/dist/tools/getPriceLists.js +92 -0
  36. package/dist/tools/getProductById.js +171 -0
  37. package/dist/tools/getProductVariantsDetailed.js +139 -0
  38. package/dist/tools/getProducts.js +155 -0
  39. package/dist/tools/getShopInfo.js +74 -0
  40. package/dist/tools/manageCustomerAddress.js +149 -0
  41. package/dist/tools/manageProductOptions.js +293 -0
  42. package/dist/tools/manageProductVariants.js +203 -0
  43. package/dist/tools/manageTags.js +79 -0
  44. package/dist/tools/mergeCustomers.js +74 -0
  45. package/dist/tools/orderCancel.js +77 -0
  46. package/dist/tools/orderCloseOpen.js +74 -0
  47. package/dist/tools/orderMarkAsPaid.js +51 -0
  48. package/dist/tools/registry.js +112 -0
  49. package/dist/tools/setInventoryQuantities.js +74 -0
  50. package/dist/tools/setMetafields.js +61 -0
  51. package/dist/tools/updateCustomer.js +119 -0
  52. package/dist/tools/updateOrder.js +131 -0
  53. package/dist/tools/updateProduct.js +132 -0
  54. package/package.json +67 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Shopify MCP Server Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,558 @@
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 (1 tool)
16
+ - **Pagination & Sorting**: Cursor-based pagination and sort keys on all list queries
17
+ - **Advanced Filtering**: Pass-through Shopify query syntax for all list endpoints
18
+ - **GraphQL Integration**: Direct integration with Shopify's GraphQL Admin API (2026-01)
19
+ - **Comprehensive Error Handling**: Clear error messages for API and authentication issues
20
+
21
+ ## Prerequisites
22
+
23
+ 1. Node.js (version 18 or higher)
24
+ 2. A Shopify store with a custom app (see setup instructions below)
25
+
26
+ ## Setup
27
+
28
+ ### Authentication
29
+
30
+ This server supports two authentication methods:
31
+
32
+ #### Option 1: Client Credentials (Dev Dashboard apps, January 2026+)
33
+
34
+ As of January 1, 2026, new Shopify apps are created in the **Dev Dashboard** and use OAuth client credentials instead of static access tokens.
35
+
36
+ 1. From your Shopify admin, go to **Settings** > **Apps and sales channels**
37
+ 2. Click **Develop apps** > **Build app in dev dashboard**
38
+ 3. Create a new app and configure **Admin API scopes**:
39
+ - `read_products`, `write_products`
40
+ - `read_customers`, `write_customers`
41
+ - `read_orders`, `write_orders`
42
+ 4. Install the app on your store
43
+ 5. Copy your **Client ID** and **Client Secret** from the app's API credentials
44
+
45
+ The server will automatically exchange these for an access token and refresh it before it expires (tokens are valid for ~24 hours).
46
+
47
+ #### Option 2: Static Access Token (legacy apps)
48
+
49
+ If you have an existing custom app with a static `shpat_` access token, you can still use it directly.
50
+
51
+ This package is not currently published to npm — clone the repo and build it locally:
52
+
53
+ ```bash
54
+ git clone https://github.com/yoffi-digital/mcp-shopify-yoffi.git
55
+ cd mcp-shopify-yoffi
56
+ npm install
57
+ npm run build
58
+ ```
59
+
60
+ This produces `dist/index.js`, which the commands below reference directly.
61
+
62
+ ### Usage with Claude Desktop
63
+
64
+ **Client Credentials (recommended):**
65
+
66
+ ```json
67
+ {
68
+ "mcpServers": {
69
+ "shopify": {
70
+ "command": "node",
71
+ "args": [
72
+ "/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
73
+ "--clientId",
74
+ "<YOUR_CLIENT_ID>",
75
+ "--clientSecret",
76
+ "<YOUR_CLIENT_SECRET>",
77
+ "--domain",
78
+ "<YOUR_SHOP>.myshopify.com"
79
+ ]
80
+ }
81
+ }
82
+ }
83
+ ```
84
+
85
+ **Static Access Token (legacy):**
86
+
87
+ ```json
88
+ {
89
+ "mcpServers": {
90
+ "shopify": {
91
+ "command": "node",
92
+ "args": [
93
+ "/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
94
+ "--accessToken",
95
+ "<YOUR_ACCESS_TOKEN>",
96
+ "--domain",
97
+ "<YOUR_SHOP>.myshopify.com"
98
+ ]
99
+ }
100
+ }
101
+ }
102
+ ```
103
+
104
+ Locations for the Claude Desktop config file:
105
+
106
+ - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
107
+ - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
108
+
109
+ ### Usage with Claude Code
110
+
111
+ **Client Credentials:**
112
+
113
+ ```bash
114
+ claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
115
+ --clientId YOUR_CLIENT_ID \
116
+ --clientSecret YOUR_CLIENT_SECRET \
117
+ --domain your-store.myshopify.com
118
+ ```
119
+
120
+ **Static Access Token (legacy):**
121
+
122
+ ```bash
123
+ claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
124
+ --accessToken YOUR_ACCESS_TOKEN \
125
+ --domain your-store.myshopify.com
126
+ ```
127
+
128
+ ### Alternative: Run Locally with Environment Variables
129
+
130
+ If you prefer to use environment variables instead of command-line arguments:
131
+
132
+ 1. Create a `.env` file with your Shopify credentials:
133
+
134
+ **Client Credentials:**
135
+ ```
136
+ SHOPIFY_CLIENT_ID=your_client_id
137
+ SHOPIFY_CLIENT_SECRET=your_client_secret
138
+ MYSHOPIFY_DOMAIN=your-store.myshopify.com
139
+ ```
140
+
141
+ **Static Access Token (legacy):**
142
+ ```
143
+ SHOPIFY_ACCESS_TOKEN=your_access_token
144
+ MYSHOPIFY_DOMAIN=your-store.myshopify.com
145
+ ```
146
+
147
+ 2. Run the server:
148
+ ```
149
+ node dist/index.js
150
+ ```
151
+
152
+ ### Additional Options
153
+
154
+ - `--apiVersion`: Specify the Shopify API version (default: `2026-01`). Can also be set via `SHOPIFY_API_VERSION` environment variable.
155
+
156
+ ## Available Tools (32)
157
+
158
+ ### Pagination, Sorting & Filtering
159
+
160
+ All list query tools (`get-products`, `get-customers`, `get-orders`, `get-customer-orders`) support:
161
+
162
+ - **Cursor-based pagination**: `after` / `before` (cursor strings), with `pageInfo` in the response (`hasNextPage`, `hasPreviousPage`, `startCursor`, `endCursor`)
163
+ - **Sorting**: `sortKey` (enum specific to each resource) and `reverse` (boolean)
164
+ - **Advanced filtering**: `query` or `searchQuery` parameter accepting [Shopify query syntax](https://shopify.dev/docs/api/usage/search-syntax)
165
+
166
+ ### Product Management (8 tools)
167
+
168
+ 1. **`get-products`**
169
+
170
+ - Get all products or search by title with pagination and sorting
171
+ - Inputs:
172
+ - `searchTitle` (string, optional): Filter products by title (wraps in `title:*...*`)
173
+ - `limit` (number, default: 10): Maximum number of products to return
174
+ - `query` (string, optional): Raw Shopify query string (e.g. `"status:active vendor:Nike tag:sale"`)
175
+ - `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `INVENTORY_TOTAL`, `PRODUCT_TYPE`, `PUBLISHED_AT`, `RELEVANCE`, `TITLE`, `UPDATED_AT`, `VENDOR`
176
+ - `reverse` (boolean, optional): Reverse the sort order
177
+ - `after` / `before` (string, optional): Pagination cursors
178
+
179
+ 2. **`get-product-by-id`**
180
+
181
+ - Get a specific product by ID with full details including SEO, options, media, variants, and collections
182
+ - Inputs:
183
+ - `productId` (string, required): Shopify product GID
184
+ - Returns: `productType`, `descriptionHtml`, `seo`, `options` (with `optionValues`), `media` (images), `variants`, `collections`, `tags`, `vendor`, price range, inventory
185
+
186
+ 3. **`create-product`**
187
+
188
+ - 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.
189
+ - Inputs:
190
+ - `title` (string, required): Title of the product
191
+ - `descriptionHtml` (string, optional): Description with HTML
192
+ - `handle` (string, optional): URL slug. Auto-generated from title if omitted
193
+ - `vendor` (string, optional): Vendor of the product
194
+ - `productType` (string, optional): Type of the product
195
+ - `tags` (array of strings, optional): Product tags
196
+ - `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`. Default `"DRAFT"`
197
+ - `seo` (object, optional): `{ title, description }` for search engines
198
+ - `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
199
+ - `productOptions` (array of objects, optional): Options to create inline, e.g. `[{ name: "Size", values: [{ name: "S" }, { name: "M" }] }]`. Max 3 options.
200
+ - `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
201
+
202
+ 4. **`update-product`**
203
+
204
+ - Update an existing product's fields
205
+ - Inputs:
206
+ - `id` (string, required): Shopify product GID
207
+ - `title` (string, optional): New title
208
+ - `descriptionHtml` (string, optional): New description
209
+ - `handle` (string, optional): New URL slug
210
+ - `vendor` (string, optional): New vendor
211
+ - `productType` (string, optional): New product type
212
+ - `tags` (array of strings, optional): New tags (overwrites existing)
213
+ - `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`
214
+ - `seo` (object, optional): `{ title, description }` for search engines
215
+ - `metafields` (array of objects, optional): Metafields to set or update
216
+ - `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
217
+ - `collectionsToLeave` (array of strings, optional): Collection GIDs to remove the product from
218
+ - `redirectNewHandle` (boolean, optional): If true, old handle redirects to new handle
219
+
220
+ 5. **`delete-product`**
221
+
222
+ - Delete a product
223
+ - Inputs:
224
+ - `id` (string, required): Shopify product GID
225
+
226
+ 6. **`manage-product-options`**
227
+
228
+ - Create, update, or delete product options (e.g. Size, Color)
229
+ - Inputs:
230
+ - `productId` (string, required): Shopify product GID
231
+ - `action` (string, required): `"create"`, `"update"`, or `"delete"`
232
+ - `variantStrategy` (string, optional): `"LEAVE_AS_IS"` (default) or `"CREATE"` — controls whether new variant combinations are generated when adding options
233
+ - For `action: "create"`:
234
+ - `options` (array, required): Options to create, e.g. `[{ name: "Size", values: ["S", "M", "L"] }]`
235
+ - For `action: "update"`:
236
+ - `optionId` (string, required): Option GID to update
237
+ - `name` (string, optional): New name for the option
238
+ - `position` (number, optional): New position
239
+ - `valuesToAdd` (array of strings, optional): Values to add
240
+ - `valuesToDelete` (array of strings, optional): Value GIDs to remove
241
+ - For `action: "delete"`:
242
+ - `optionIds` (array of strings, required): Option GIDs to delete
243
+
244
+ 7. **`manage-product-variants`**
245
+
246
+ - Create or update product variants in bulk
247
+ - Inputs:
248
+ - `productId` (string, required): Shopify product GID
249
+ - `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"`
250
+ - `variants` (array, required): Variants to create or update. Each variant:
251
+ - `id` (string, optional): Variant GID for updates. Omit to create new
252
+ - `price` (string, optional): Price, e.g. `"49.00"`
253
+ - `compareAtPrice` (string, optional): Compare-at price for showing discounts
254
+ - `sku` (string, optional): SKU (mapped to `inventoryItem.sku`)
255
+ - `tracked` (boolean, optional): Whether inventory is tracked. Set `false` for print-on-demand
256
+ - `taxable` (boolean, optional): Whether the variant is taxable
257
+ - `barcode` (string, optional): Barcode
258
+ - `weight` (number, optional): Weight of the variant
259
+ - `weightUnit` (string, optional): `"GRAMS"`, `"KILOGRAMS"`, `"OUNCES"`, or `"POUNDS"`
260
+ - `optionValues` (array, optional): Option values, e.g. `[{ optionName: "Size", name: "A4" }]`
261
+
262
+ 8. **`delete-product-variants`**
263
+
264
+ - Delete one or more variants from a product
265
+ - Inputs:
266
+ - `productId` (string, required): Shopify product GID
267
+ - `variantIds` (array of strings, required): Variant GIDs to delete
268
+
269
+ ### Customer Management (8 tools)
270
+
271
+ 1. **`get-customers`**
272
+
273
+ - List customers with search, pagination, and sorting
274
+ - Inputs:
275
+ - `searchQuery` (string, optional): Freetext or Shopify query syntax (e.g. `"country:US tag:vip orders_count:>5"`)
276
+ - `limit` (number, default: 10): Maximum number of customers to return
277
+ - `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `LAST_UPDATE`, `LOCATION`, `NAME`, `ORDERS_COUNT`, `RELEVANCE`, `TOTAL_SPENT`, `UPDATED_AT`
278
+ - `reverse` (boolean, optional): Reverse the sort order
279
+ - `after` / `before` (string, optional): Pagination cursors
280
+
281
+ 2. **`get-customer-by-id`**
282
+
283
+ - Get a single customer by ID with full details
284
+ - Inputs:
285
+ - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
286
+ - Returns: name, email, phone, addresses, tags, note, tax status, amount spent, order count, metafields
287
+
288
+ 3. **`create-customer`**
289
+
290
+ - Create a new customer
291
+ - Inputs:
292
+ - `firstName` (string, optional): Customer's first name
293
+ - `lastName` (string, optional): Customer's last name
294
+ - `email` (string, optional): Customer's email address
295
+ - `phone` (string, optional): Customer's phone number
296
+ - `tags` (array of strings, optional): Tags to apply
297
+ - `note` (string, optional): Note about the customer
298
+ - `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
299
+ - `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
300
+ - `addresses` (array of objects, optional): Customer addresses (`address1`, `address2`, `city`, `provinceCode`, `zip`, `country`, `phone`)
301
+
302
+ 4. **`update-customer`**
303
+
304
+ - Update a customer's information
305
+ - Inputs:
306
+ - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
307
+ - `firstName` (string, optional): Customer's first name
308
+ - `lastName` (string, optional): Customer's last name
309
+ - `email` (string, optional): Customer's email address
310
+ - `phone` (string, optional): Customer's phone number
311
+ - `tags` (array of strings, optional): Tags to apply to the customer
312
+ - `note` (string, optional): Note about the customer
313
+ - `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
314
+ - `emailMarketingConsent` (object, optional): Email marketing consent settings
315
+ - `marketingState` (string, required): `"NOT_SUBSCRIBED"`, `"SUBSCRIBED"`, `"UNSUBSCRIBED"`, or `"PENDING"`
316
+ - `consentUpdatedAt` (string, optional): ISO 8601 timestamp
317
+ - `marketingOptInLevel` (string, optional): `"SINGLE_OPT_IN"`, `"CONFIRMED_OPT_IN"`, or `"UNKNOWN"`
318
+ - `metafields` (array of objects, optional): Customer metafields
319
+
320
+ 5. **`delete-customer`**
321
+
322
+ - Delete a customer
323
+ - Inputs:
324
+ - `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
325
+
326
+ 6. **`customer-merge`**
327
+
328
+ - Merge two customer records into one
329
+ - Inputs:
330
+ - `customerOneId` (string, required): GID of the first customer
331
+ - `customerTwoId` (string, required): GID of the second customer
332
+ - `overrideFields` (object, optional): Override which fields to keep from which customer (firstName, lastName, email, phone, defaultAddress, note, tags)
333
+
334
+ 7. **`manage-customer-address`**
335
+
336
+ - Create, update, or delete a customer's mailing address
337
+ - Inputs:
338
+ - `customerId` (string, required): Customer GID
339
+ - `action` (string, required): `"create"`, `"update"`, or `"delete"`
340
+ - `addressId` (string, optional): Address GID (required for update/delete)
341
+ - `address` (object, optional): Address fields (required for create/update): `address1`, `address2`, `city`, `company`, `countryCode`, `firstName`, `lastName`, `phone`, `provinceCode`, `zip`
342
+ - `setAsDefault` (boolean, optional): Set as customer's default address
343
+
344
+ ### Order Management (10 tools)
345
+
346
+ 1. **`get-orders`**
347
+
348
+ - Get orders with filtering, pagination, and sorting
349
+ - Inputs:
350
+ - `status` (string, optional): `"any"`, `"open"`, `"closed"`, or `"cancelled"`. Default `"any"`
351
+ - `limit` (number, default: 10): Maximum number of orders to return
352
+ - `query` (string, optional): Raw Shopify query string (e.g. `"financial_status:paid fulfillment_status:shipped tag:rush"`)
353
+ - `sortKey` (string, optional): One of `CREATED_AT`, `ORDER_NUMBER`, `TOTAL_PRICE`, `FINANCIAL_STATUS`, `FULFILLMENT_STATUS`, `UPDATED_AT`, `CUSTOMER_NAME`, `PROCESSED_AT`, `ID`, `RELEVANCE`
354
+ - `reverse` (boolean, optional): Reverse the sort order
355
+ - `after` / `before` (string, optional): Pagination cursors
356
+
357
+ 2. **`get-order-by-id`**
358
+
359
+ - Get a specific order by ID with smart lookup — accepts order name (`#77235` or `77235`), numeric ID (`8054938337547`), or full GID (`gid://shopify/Order/...`)
360
+ - Inputs:
361
+ - `orderId` (string, required): Order name, numeric ID, or full GID
362
+ - Returns: pricing, customer, shipping/billing addresses, line items, tags, notes, metafields, cancel reason, return status, discount codes, PO number, timestamps
363
+
364
+ 3. **`update-order`**
365
+
366
+ - Update an existing order
367
+ - Inputs:
368
+ - `id` (string, required): Shopify order GID
369
+ - `tags` (array of strings, optional): New tags for the order
370
+ - `email` (string, optional): Update customer email on the order
371
+ - `note` (string, optional): Order notes
372
+ - `phone` (string, optional): Phone number for the order
373
+ - `poNumber` (string, optional): Purchase order number
374
+ - `customAttributes` (array of objects, optional): Custom key-value attributes
375
+ - `metafields` (array of objects, optional): Order metafields
376
+ - `shippingAddress` (object, optional): Shipping address fields
377
+
378
+ 4. **`get-customer-orders`**
379
+
380
+ - Get orders for a specific customer with pagination and sorting
381
+ - Inputs:
382
+ - `customerId` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
383
+ - `limit` (number, default: 10): Maximum number of orders to return
384
+ - `sortKey` (string, optional): Same sort keys as `get-orders`
385
+ - `reverse` (boolean, optional): Reverse the sort order
386
+ - `after` / `before` (string, optional): Pagination cursors
387
+
388
+ 5. **`order-cancel`**
389
+
390
+ - Cancel an order with options for refunding, restocking, and customer notification. **Irreversible.**
391
+ - Inputs:
392
+ - `orderId` (string, required): Order GID
393
+ - `reason` (string, required): `"CUSTOMER"`, `"DECLINED"`, `"FRAUD"`, `"INVENTORY"`, `"OTHER"`, or `"STAFF"`
394
+ - `restock` (boolean, required): Whether to restock inventory
395
+ - `notifyCustomer` (boolean, default: false): Notify the customer
396
+ - `staffNote` (string, optional): Internal note
397
+ - `refund` (boolean, optional): Refund to original payment method
398
+
399
+ 6. **`order-close-open`**
400
+
401
+ - Close or reopen an order
402
+ - Inputs:
403
+ - `orderId` (string, required): Order GID
404
+ - `action` (string, required): `"close"` or `"open"`
405
+
406
+ 7. **`order-mark-as-paid`**
407
+
408
+ - Mark an order as paid (for manual/offline payments)
409
+ - Inputs:
410
+ - `orderId` (string, required): Order GID
411
+
412
+ 8. **`create-fulfillment`**
413
+
414
+ - Create a fulfillment (mark items as shipped) with optional tracking
415
+ - Inputs:
416
+ - `lineItemsByFulfillmentOrder` (array, required): Fulfillment orders and line items to fulfill
417
+ - `trackingInfo` (object, optional): `{ number, url, company }` tracking details
418
+ - `notifyCustomer` (boolean, default: false): Send shipping notification
419
+
420
+ 9. **`refund-create`**
421
+
422
+ - Create a full or partial refund with optional restocking
423
+ - Inputs:
424
+ - `orderId` (string, required): Order GID
425
+ - `refundLineItems` (array, optional): Line items to refund with `lineItemId`, `quantity`, `restockType` (`CANCEL`/`RETURN`/`NO_RESTOCK`), `locationId`
426
+ - `shipping` (object, optional): `{ amount, fullRefund }` shipping refund
427
+ - `note` (string, optional): Refund note
428
+ - `notify` (boolean, optional): Send refund notification
429
+
430
+ 10. **`create-draft-order`**
431
+
432
+ - Create a draft order for phone/chat sales, invoicing, or wholesale
433
+ - Inputs:
434
+ - `lineItems` (array, required): Product variants (`variantId`) or custom items (`title` + price). Max 499
435
+ - `customerId` (string, optional): Customer GID
436
+ - `email`, `phone`, `note`, `tags`, `poNumber` (optional)
437
+ - `shippingAddress`, `billingAddress` (objects, optional)
438
+ - `appliedDiscount` (object, optional): `{ title, value, valueType }` order-level discount
439
+
440
+ ### Draft Order Management (1 tool)
441
+
442
+ 1. **`complete-draft-order`**
443
+
444
+ - Complete a draft order, converting it into a real order
445
+ - Inputs:
446
+ - `draftOrderId` (string, required): Draft order GID
447
+ - `paymentGatewayId` (string, optional): Payment gateway GID
448
+
449
+ ### Metafield Management (3 tools)
450
+
451
+ 1. **`get-metafields`**
452
+
453
+ - Get metafields for any Shopify resource (products, orders, customers, variants, collections, etc.)
454
+ - Inputs:
455
+ - `ownerId` (string, required): GID of any resource
456
+ - `namespace` (string, optional): Filter by namespace
457
+ - `first` (number, default: 25): Number of metafields to return
458
+ - `after` (string, optional): Pagination cursor
459
+
460
+ 2. **`set-metafields`**
461
+
462
+ - Set metafields on any Shopify resource. Creates or updates up to 25 metafields atomically
463
+ - Inputs:
464
+ - `metafields` (array, required): Metafields to set, each with `ownerId`, `key`, `value`, and optional `namespace`, `type`
465
+
466
+ 3. **`delete-metafields`**
467
+
468
+ - Delete metafields from any Shopify resource
469
+ - Inputs:
470
+ - `metafields` (array, required): Metafields to delete, each with `ownerId`, `namespace`, `key`
471
+
472
+ ### Inventory Management (1 tool)
473
+
474
+ 1. **`inventory-set-quantities`**
475
+
476
+ - Set absolute inventory quantities for items at specific locations
477
+ - Inputs:
478
+ - `reason` (string, required): Reason for change (e.g. `"correction"`, `"cycle_count_available"`)
479
+ - `name` (string, required): `"available"` or `"on_hand"`
480
+ - `quantities` (array, required): Items with `inventoryItemId`, `locationId`, `quantity`
481
+
482
+ ### Tag Management (1 tool)
483
+
484
+ 1. **`manage-tags`**
485
+
486
+ - Add or remove tags on any taggable resource (orders, products, customers, draft orders, articles)
487
+ - Inputs:
488
+ - `id` (string, required): GID of the resource
489
+ - `tags` (array of strings, required): Tags to add or remove
490
+ - `action` (string, required): `"add"` or `"remove"`
491
+
492
+ ### Discount Management (2 tools)
493
+
494
+ 1. **`create-discount`**
495
+
496
+ - Create a basic discount code (percentage or fixed amount), applied store-wide or scoped to specific collections and/or products
497
+ - Inputs:
498
+ - `title` (string, required): Internal title for the discount
499
+ - `code` (string, required): The discount code customers enter at checkout
500
+ - `valueType` (string, required): `"PERCENTAGE"` or `"FIXED_AMOUNT"`
501
+ - `value` (number, required): Decimal between 0 and 1 for `PERCENTAGE` (e.g. `0.15` for 15%), or the currency amount for `FIXED_AMOUNT`
502
+ - `startsAt` (string, required): ISO 8601 datetime the discount becomes active
503
+ - `endsAt` (string, optional): ISO 8601 datetime the discount expires
504
+ - `appliesOncePerCustomer` (boolean, optional): Limit each customer to a single use
505
+ - `usageLimit` (number, optional): Total number of redemptions allowed
506
+ - `includeCollectionIds` (array of strings, optional): Collection GIDs to scope the discount to (mutually exclusive with the product ID fields)
507
+ - `excludeCollectionIds` (array of strings, optional): Collection GIDs to exclude from an otherwise store-wide discount
508
+ - `includeProductIds` (array of strings, optional): Product GIDs to scope the discount to (mutually exclusive with the collection ID fields)
509
+ - `excludeProductIds` (array of strings, optional): Product GIDs to exclude from an otherwise store-wide discount
510
+ - `combinesWith` (object, optional): `{ productDiscounts, orderDiscounts, shippingDiscounts }` combination rules
511
+
512
+ 2. **`create-automatic-discount`**
513
+
514
+ - 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
515
+ - Inputs:
516
+ - `title` (string, required): Title for the discount, shown to customers at checkout
517
+ - `valueType` (string, required): `"PERCENTAGE"` or `"FIXED_AMOUNT"`
518
+ - `value` (number, required): Decimal between 0 and 1 for `PERCENTAGE` (e.g. `0.15` for 15%), or the currency amount for `FIXED_AMOUNT`
519
+ - `startsAt` (string, required): ISO 8601 datetime the discount becomes active
520
+ - `endsAt` (string, optional): ISO 8601 datetime the discount expires
521
+ - `minimumSubtotal` (number, optional): Minimum order subtotal required for the discount to apply
522
+ - `includeCollectionIds` (array of strings, optional): Collection GIDs to scope the discount to (mutually exclusive with the product ID fields)
523
+ - `excludeCollectionIds` (array of strings, optional): Collection GIDs to exclude from an otherwise store-wide discount
524
+ - `includeProductIds` (array of strings, optional): Product GIDs to scope the discount to (mutually exclusive with the collection ID fields)
525
+ - `excludeProductIds` (array of strings, optional): Product GIDs to exclude from an otherwise store-wide discount
526
+ - `combinesWith` (object, optional): `{ productDiscounts, orderDiscounts, shippingDiscounts }` combination rules
527
+
528
+ ### Order Query Filter Reference
529
+
530
+ The `get-orders` tool's `query` parameter supports [Shopify search syntax](https://shopify.dev/docs/api/usage/search-syntax):
531
+
532
+ | Filter | Example |
533
+ |--------|---------|
534
+ | `name` | `name:#77235` |
535
+ | `created_at` | `created_at:>2024-01-01` or `created_at:2024-01-01..2024-03-31` |
536
+ | `updated_at` | `updated_at:>2024-06-01` |
537
+ | `financial_status` | `financial_status:paid` |
538
+ | `fulfillment_status` | `fulfillment_status:shipped` |
539
+ | `status` | `status:open` |
540
+ | `email` | `email:customer@example.com` |
541
+ | `tag` / `tag_not` | `tag:vip tag_not:wholesale` |
542
+ | `discount_code` | `discount_code:SUMMER20` |
543
+ | `sku` | `sku:PROD-001` |
544
+ | `risk_level` | `risk_level:high` |
545
+ | `gateway` | `gateway:shopify_payments` |
546
+ | `test` | `test:true` |
547
+
548
+ ## Debugging
549
+
550
+ If you encounter issues, check Claude Desktop's MCP logs:
551
+
552
+ ```
553
+ tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
554
+ ```
555
+
556
+ ## License
557
+
558
+ MIT
package/dist/index.js ADDED
@@ -0,0 +1,91 @@
1
+ #!/usr/bin/env node
2
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4
+ import dotenv from "dotenv";
5
+ import { GraphQLClient } from "graphql-request";
6
+ import minimist from "minimist";
7
+ import { ShopifyAuth } from "./lib/shopifyAuth.js";
8
+ import { tools } from "./tools/registry.js";
9
+ // Parse command line arguments
10
+ const argv = minimist(process.argv.slice(2));
11
+ // Load environment variables from .env file (if it exists)
12
+ dotenv.config();
13
+ // Define environment variables - from command line or .env file
14
+ const SHOPIFY_ACCESS_TOKEN = argv.accessToken || process.env.SHOPIFY_ACCESS_TOKEN;
15
+ const SHOPIFY_CLIENT_ID = argv.clientId || process.env.SHOPIFY_CLIENT_ID;
16
+ const SHOPIFY_CLIENT_SECRET = argv.clientSecret || process.env.SHOPIFY_CLIENT_SECRET;
17
+ const MYSHOPIFY_DOMAIN = argv.domain || process.env.MYSHOPIFY_DOMAIN;
18
+ const useClientCredentials = !!(SHOPIFY_CLIENT_ID && SHOPIFY_CLIENT_SECRET);
19
+ // Store in process.env for backwards compatibility
20
+ process.env.MYSHOPIFY_DOMAIN = MYSHOPIFY_DOMAIN;
21
+ // Validate required environment variables
22
+ if (!SHOPIFY_ACCESS_TOKEN && !useClientCredentials) {
23
+ console.error("Error: Authentication credentials are required.");
24
+ console.error("");
25
+ console.error("Option 1 — Static access token (legacy apps):");
26
+ console.error(" --accessToken=shpat_xxxxx");
27
+ console.error("");
28
+ console.error("Option 2 — Client credentials (Dev Dashboard apps, Jan 2026+):");
29
+ console.error(" --clientId=your_client_id --clientSecret=your_client_secret");
30
+ process.exit(1);
31
+ }
32
+ if (!MYSHOPIFY_DOMAIN) {
33
+ console.error("Error: MYSHOPIFY_DOMAIN is required.");
34
+ console.error("Please provide it via command line argument or .env file.");
35
+ console.error(" Command line: --domain=your-store.myshopify.com");
36
+ process.exit(1);
37
+ }
38
+ // Resolve access token (client credentials or static)
39
+ let accessToken;
40
+ let auth = null;
41
+ if (useClientCredentials) {
42
+ auth = new ShopifyAuth({
43
+ clientId: SHOPIFY_CLIENT_ID,
44
+ clientSecret: SHOPIFY_CLIENT_SECRET,
45
+ shopDomain: MYSHOPIFY_DOMAIN,
46
+ });
47
+ accessToken = await auth.initialize();
48
+ }
49
+ else {
50
+ accessToken = SHOPIFY_ACCESS_TOKEN;
51
+ }
52
+ process.env.SHOPIFY_ACCESS_TOKEN = accessToken;
53
+ // Create Shopify GraphQL client
54
+ const API_VERSION = argv.apiVersion || process.env.SHOPIFY_API_VERSION || "2026-01";
55
+ const shopifyClient = new GraphQLClient(`https://${MYSHOPIFY_DOMAIN}/admin/api/${API_VERSION}/graphql.json`, {
56
+ headers: {
57
+ "X-Shopify-Access-Token": accessToken,
58
+ "Content-Type": "application/json"
59
+ }
60
+ });
61
+ // Let the auth manager hot-swap the token header on refresh
62
+ if (auth) {
63
+ auth.setGraphQLClient(shopifyClient);
64
+ }
65
+ // Initialize all tools with the shared GraphQL client
66
+ for (const tool of tools) {
67
+ tool.initialize(shopifyClient);
68
+ }
69
+ // Set up MCP server
70
+ const server = new McpServer({
71
+ name: "shopify",
72
+ version: "1.0.0",
73
+ description: "MCP Server for Shopify API, enabling interaction with store data through GraphQL API"
74
+ });
75
+ // Register all tools with the MCP server
76
+ for (const tool of tools) {
77
+ server.tool(tool.name, tool.schema.shape, async (args) => {
78
+ const result = await tool.execute(args);
79
+ return {
80
+ content: [{ type: "text", text: JSON.stringify(result) }]
81
+ };
82
+ });
83
+ }
84
+ // Start the server
85
+ const transport = new StdioServerTransport();
86
+ server
87
+ .connect(transport)
88
+ .then(() => { })
89
+ .catch((error) => {
90
+ console.error("Failed to start Shopify MCP Server:", error);
91
+ });