@klaudworks/shopify-mcp 1.1.0

package/dist/tools/setInventoryQuantities.js

@@ -0,0 +1,74 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const SetInventoryQuantitiesInputSchema = z.object({
+    reason: z.string().describe("Reason for the quantity change (e.g. 'correction', 'cycle_count_available', 'received')"),
+    name: z.enum(["available", "on_hand"]).describe("Which quantity to set: 'available' or 'on_hand'"),
+    quantities: z
+        .array(z.object({
+        inventoryItemId: z.string().describe("Inventory item GID"),
+        locationId: z.string().describe("Location GID"),
+        quantity: z.number().describe("Absolute quantity to set"),
+    }))
+        .min(1)
+        .describe("Quantities to set for each inventory item at each location"),
+    ignoreCompareQuantity: z.boolean().default(true).describe("Skip compare-and-set check (default true for simplicity)"),
+});
+let shopifyClient;
+const setInventoryQuantities = {
+    name: "inventory-set-quantities",
+    description: "Set absolute inventory quantities for items at specific locations. Use for inventory corrections, cycle counts, etc.",
+    schema: SetInventoryQuantitiesInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation inventorySetQuantities($input: InventorySetQuantitiesInput!) {
+          inventorySetQuantities(input: $input) {
+            inventoryAdjustmentGroup {
+              reason
+              changes {
+                name
+                delta
+                quantityAfterChange
+                item {
+                  id
+                  sku
+                }
+                location {
+                  id
+                  name
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+              code
+            }
+          }
+        }
+      `;
+            const data = (await shopifyClient.request(query, {
+                input: {
+                    reason: input.reason,
+                    name: input.name,
+                    ignoreCompareQuantity: input.ignoreCompareQuantity,
+                    quantities: input.quantities,
+                },
+            }));
+            checkUserErrors(data.inventorySetQuantities.userErrors, "set inventory quantities");
+            return {
+                adjustmentGroup: data.inventorySetQuantities.inventoryAdjustmentGroup,
+            };
+        }
+        catch (error) {
+            handleToolError("set inventory quantities", error);
+        }
+    },
+};
+export { setInventoryQuantities };

package/dist/tools/setMetafields.js

@@ -0,0 +1,61 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const SetMetafieldsInputSchema = z.object({
+    metafields: z
+        .array(z.object({
+        ownerId: z.string().describe("GID of the resource (product, order, customer, variant, etc.)"),
+        namespace: z.string().optional().describe("Metafield namespace. If omitted, app-reserved namespace is used."),
+        key: z.string().describe("Unique identifier within its namespace (2-64 chars)"),
+        value: z.string().describe("The value to set (always stored as string)"),
+        type: z.string().optional().describe("Metafield type, e.g. 'single_line_text_field', 'json', 'number_integer'. Required if no definition exists."),
+    }))
+        .min(1)
+        .max(25)
+        .describe("Metafields to set (max 25). Works on any resource: products, orders, customers, variants, collections, etc."),
+});
+let shopifyClient;
+const setMetafields = {
+    name: "set-metafields",
+    description: "Set metafields on any Shopify resource (products, orders, customers, variants, collections, etc.). Creates or updates up to 25 metafields atomically.",
+    schema: SetMetafieldsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
+          metafieldsSet(metafields: $metafields) {
+            metafields {
+              id
+              namespace
+              key
+              value
+              type
+              ownerType
+            }
+            userErrors {
+              field
+              message
+              code
+            }
+          }
+        }
+      `;
+            const data = (await shopifyClient.request(query, {
+                metafields: input.metafields,
+            }));
+            checkUserErrors(data.metafieldsSet.userErrors, "set metafields");
+            return {
+                metafields: data.metafieldsSet.metafields || [],
+            };
+        }
+        catch (error) {
+            handleToolError("set metafields", error);
+        }
+    },
+};
+export { setMetafields };

package/dist/tools/updateCustomer.js

@@ -0,0 +1,119 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Input schema for updating a customer
+const UpdateCustomerInputSchema = z.object({
+    id: z.string().regex(/^\d+$/, "Customer ID must be numeric"),
+    firstName: z.string().optional(),
+    lastName: z.string().optional(),
+    email: z.string().email().optional(),
+    phone: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    note: z.string().optional(),
+    emailMarketingConsent: z
+        .object({
+        marketingState: z.enum(["NOT_SUBSCRIBED", "SUBSCRIBED", "UNSUBSCRIBED", "PENDING"]),
+        consentUpdatedAt: z.string().optional(),
+        marketingOptInLevel: z.enum(["SINGLE_OPT_IN", "CONFIRMED_OPT_IN", "UNKNOWN"]).optional()
+    })
+        .optional(),
+    taxExempt: z.boolean().optional(),
+    metafields: z
+        .array(z.object({
+        id: z.string().optional(),
+        namespace: z.string().optional(),
+        key: z.string().optional(),
+        value: z.string(),
+        type: z.string().optional()
+    }))
+        .optional()
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const updateCustomer = {
+    name: "update-customer",
+    description: "Update a customer's information",
+    schema: UpdateCustomerInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { id, ...customerFields } = input;
+            // Convert numeric ID to GID format
+            const customerGid = `gid://shopify/Customer/${id}`;
+            const query = gql `
+        #graphql
+
+        mutation customerUpdate($input: CustomerInput!) {
+          customerUpdate(input: $input) {
+            customer {
+              id
+              firstName
+              lastName
+              defaultEmailAddress {
+                emailAddress
+              }
+              defaultPhoneNumber {
+                phoneNumber
+              }
+              tags
+              note
+              taxExempt
+              emailMarketingConsent {
+                marketingState
+                consentUpdatedAt
+                marketingOptInLevel
+              }
+              metafields(first: 10) {
+                edges {
+                  node {
+                    id
+                    namespace
+                    key
+                    value
+                  }
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const variables = {
+                input: {
+                    id: customerGid,
+                    ...customerFields
+                }
+            };
+            const data = (await shopifyClient.request(query, variables));
+            checkUserErrors(data.customerUpdate.userErrors, "update customer");
+            // Format and return the updated customer
+            const customer = data.customerUpdate.customer;
+            // Format metafields if they exist
+            const metafields = customer.metafields?.edges.map((edge) => edge.node) || [];
+            return {
+                customer: {
+                    id: customer.id,
+                    firstName: customer.firstName,
+                    lastName: customer.lastName,
+                    email: customer.defaultEmailAddress?.emailAddress || null,
+                    phone: customer.defaultPhoneNumber?.phoneNumber || null,
+                    tags: customer.tags,
+                    note: customer.note,
+                    taxExempt: customer.taxExempt,
+                    emailMarketingConsent: customer.emailMarketingConsent,
+                    metafields
+                }
+            };
+        }
+        catch (error) {
+            handleToolError("update customer", error);
+        }
+    }
+};
+export { updateCustomer };

package/dist/tools/updateOrder.js

@@ -0,0 +1,131 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Will be initialized in index.ts
+let shopifyClient;
+// Input schema for updateOrder
+// Based on https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderupdate
+const UpdateOrderInputSchema = z.object({
+    id: z.string().min(1),
+    tags: z.array(z.string()).optional(),
+    email: z.string().email().optional(),
+    note: z.string().optional(),
+    customAttributes: z
+        .array(z.object({
+        key: z.string(),
+        value: z.string()
+    }))
+        .optional(),
+    metafields: z
+        .array(z.object({
+        id: z.string().optional(),
+        namespace: z.string().optional(),
+        key: z.string().optional(),
+        value: z.string(),
+        type: z.string().optional()
+    }))
+        .optional(),
+    phone: z.string().optional(),
+    poNumber: z.string().optional(),
+    shippingAddress: z
+        .object({
+        address1: z.string().optional(),
+        address2: z.string().optional(),
+        city: z.string().optional(),
+        company: z.string().optional(),
+        countryCode: z.string().optional(),
+        firstName: z.string().optional(),
+        lastName: z.string().optional(),
+        phone: z.string().optional(),
+        provinceCode: z.string().optional(),
+        zip: z.string().optional()
+    })
+        .optional()
+});
+const updateOrder = {
+    name: "update-order",
+    description: "Update an existing order with new information",
+    schema: UpdateOrderInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            // Prepare input for GraphQL mutation
+            const { id, ...orderFields } = input;
+            const query = gql `
+        #graphql
+
+        mutation orderUpdate($input: OrderInput!) {
+          orderUpdate(input: $input) {
+            order {
+              id
+              name
+              email
+              note
+              tags
+              customAttributes {
+                key
+                value
+              }
+              metafields(first: 10) {
+                edges {
+                  node {
+                    id
+                    namespace
+                    key
+                    value
+                  }
+                }
+              }
+              shippingAddress {
+                address1
+                address2
+                city
+                company
+                country
+                firstName
+                lastName
+                phone
+                province
+                zip
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const variables = {
+                input: {
+                    id,
+                    ...orderFields
+                }
+            };
+            const data = (await shopifyClient.request(query, variables));
+            checkUserErrors(data.orderUpdate.userErrors, "update order");
+            // Format and return the updated order
+            const order = data.orderUpdate.order;
+            // Return the updated order data
+            return {
+                order: {
+                    id: order.id,
+                    name: order.name,
+                    email: order.email,
+                    note: order.note,
+                    tags: order.tags,
+                    customAttributes: order.customAttributes,
+                    metafields: order.metafields?.edges.map((edge) => edge.node) || [],
+                    shippingAddress: order.shippingAddress
+                }
+            };
+        }
+        catch (error) {
+            handleToolError("update order", error);
+        }
+    }
+};
+export { updateOrder };

package/dist/tools/updateProduct.js

@@ -0,0 +1,132 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Input schema for updateProduct
+const UpdateProductInputSchema = z.object({
+    id: z.string().min(1).describe("Shopify product GID, e.g. gid://shopify/Product/123"),
+    title: z.string().optional(),
+    descriptionHtml: z.string().optional(),
+    handle: z.string().optional().describe("URL slug for the product"),
+    vendor: z.string().optional(),
+    productType: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    status: z.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).optional(),
+    seo: z
+        .object({
+        title: z.string().optional(),
+        description: z.string().optional(),
+    })
+        .optional()
+        .describe("SEO title and description for search engines"),
+    metafields: z
+        .array(z.object({
+        id: z.string().optional(),
+        namespace: z.string().optional(),
+        key: z.string().optional(),
+        value: z.string(),
+        type: z.string().optional(),
+    }))
+        .optional(),
+    collectionsToJoin: z.array(z.string()).optional().describe("Collection GIDs to add the product to"),
+    collectionsToLeave: z.array(z.string()).optional().describe("Collection GIDs to remove the product from"),
+    redirectNewHandle: z.boolean().optional().describe("If true, old handle redirects to new handle"),
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const updateProduct = {
+    name: "update-product",
+    description: "Update an existing product's fields (title, description, status, tags, etc.)",
+    schema: UpdateProductInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { id, ...productFields } = input;
+            const query = gql `
+        #graphql
+
+        mutation productUpdate($product: ProductUpdateInput!) {
+          productUpdate(product: $product) {
+            product {
+              id
+              title
+              handle
+              descriptionHtml
+              vendor
+              productType
+              status
+              tags
+              seo {
+                title
+                description
+              }
+              metafields(first: 10) {
+                edges {
+                  node {
+                    id
+                    namespace
+                    key
+                    value
+                  }
+                }
+              }
+              variants(first: 20) {
+                edges {
+                  node {
+                    id
+                    title
+                    price
+                    sku
+                    selectedOptions {
+                      name
+                      value
+                    }
+                  }
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const variables = {
+                product: {
+                    id,
+                    ...productFields,
+                },
+            };
+            const data = (await shopifyClient.request(query, variables));
+            checkUserErrors(data.productUpdate.userErrors, "update product");
+            const product = data.productUpdate.product;
+            return {
+                product: {
+                    id: product.id,
+                    title: product.title,
+                    handle: product.handle,
+                    descriptionHtml: product.descriptionHtml,
+                    vendor: product.vendor,
+                    productType: product.productType,
+                    status: product.status,
+                    tags: product.tags,
+                    seo: product.seo,
+                    metafields: product.metafields?.edges.map((e) => e.node) || [],
+                    variants: product.variants?.edges.map((e) => ({
+                        id: e.node.id,
+                        title: e.node.title,
+                        price: e.node.price,
+                        sku: e.node.sku,
+                        options: e.node.selectedOptions,
+                    })) || [],
+                },
+            };
+        }
+        catch (error) {
+            handleToolError("update product", error);
+        }
+    },
+};
+export { updateProduct };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@klaudworks/shopify-mcp",
+  "version": "1.1.0",
+  "description": "MCP Server for Shopify API, enabling interaction with store data through GraphQL API",
+  "main": "dist/index.js",
+  "bin": "dist/index.js",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "start": "node dist/index.js",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "test": "echo '(no tests yet — placeholder so CI stays green; swap in node --test when tests are added)' && exit 0",
+    "prepublishOnly": "npm run build",
+    "clean": "rimraf dist"
+  },
+  "keywords": [
+    "shopify",
+    "mcp",
+    "model-context-protocol",
+    "graphql",
+    "ai",
+    "llm",
+    "claude"
+  ],
+  "author": {
+    "name": "Your Name",
+    "email": "your.email@example.com",
+    "url": "https://your-website.com"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^16.0.3",
+    "graphql": "^16.6.0",
+    "graphql-request": "^7.4.0",
+    "minimist": "^1.2.8",
+    "zod": "^3.21.4"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.2",
+    "@types/node": "^22.10.0",
+    "rimraf": "^5.0.10",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/klaudworks/shopify-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/klaudworks/shopify-mcp/issues"
+  },
+  "homepage": "https://github.com/klaudworks/shopify-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}