Shopify MCP Server

Implementation Reference

• src/tools/getCustomerOrders.ts:26-167 (handler)

  The execute function that implements the core logic for fetching customer orders from Shopify GraphQL API. It validates input, constructs a GraphQL query to fetch orders filtered by customer ID, and returns formatted order data including customer details, line items, pricing, and fulfillment status.

  execute: async (input: GetCustomerOrdersInput) => {
    try {
      const { customerId, limit } = input;
  
      // Convert the numeric customer ID to the GID format
      const customerGid = `gid://shopify/Customer/${customerId}`;
  
      // Query to get orders for a specific customer
      const query = gql`
        query GetCustomerOrders($query: String!, $first: Int!) {
          orders(query: $query, first: $first) {
            edges {
              node {
                id
                name
                createdAt
                displayFinancialStatus
                displayFulfillmentStatus
                totalPriceSet {
                  shopMoney {
                    amount
                    currencyCode
                  }
                }
                subtotalPriceSet {
                  shopMoney {
                    amount
                    currencyCode
                  }
                }
                totalShippingPriceSet {
                  shopMoney {
                    amount
                    currencyCode
                  }
                }
                totalTaxSet {
                  shopMoney {
                    amount
                    currencyCode
                  }
                }
                customer {
                  id
                  firstName
                  lastName
                  email
                }
                lineItems(first: 5) {
                  edges {
                    node {
                      id
                      title
                      quantity
                      originalTotalSet {
                        shopMoney {
                          amount
                          currencyCode
                        }
                      }
                      variant {
                        id
                        title
                        sku
                      }
                    }
                  }
                }
                tags
                note
              }
            }
          }
        }
      `;
  
      // We use the query parameter to filter orders by customer ID
      const variables = {
        query: `customer_id:${customerId}`,
        first: limit
      };
  
      const data = (await shopifyClient.request(query, variables)) as {
        orders: any;
      };
  
      // Extract and format order data
      const orders = data.orders.edges.map((edge: any) => {
        const order = edge.node;
  
        // Format line items
        const lineItems = order.lineItems.edges.map((lineItemEdge: any) => {
          const lineItem = lineItemEdge.node;
          return {
            id: lineItem.id,
            title: lineItem.title,
            quantity: lineItem.quantity,
            originalTotal: lineItem.originalTotalSet.shopMoney,
            variant: lineItem.variant
              ? {
                  id: lineItem.variant.id,
                  title: lineItem.variant.title,
                  sku: lineItem.variant.sku
                }
              : null
          };
        });
  
        return {
          id: order.id,
          name: order.name,
          createdAt: order.createdAt,
          financialStatus: order.displayFinancialStatus,
          fulfillmentStatus: order.displayFulfillmentStatus,
          totalPrice: order.totalPriceSet.shopMoney,
          subtotalPrice: order.subtotalPriceSet.shopMoney,
          totalShippingPrice: order.totalShippingPriceSet.shopMoney,
          totalTax: order.totalTaxSet.shopMoney,
          customer: order.customer
            ? {
                id: order.customer.id,
                firstName: order.customer.firstName,
                lastName: order.customer.lastName,
                email: order.customer.email
              }
            : null,
          lineItems,
          tags: order.tags,
          note: order.note
        };
      });
  
      return { orders };
    } catch (error) {
      console.error("Error fetching customer orders:", error);
      throw new Error(
        `Failed to fetch customer orders: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }

• src/tools/getCustomerOrders.ts:6-11 (schema)

  Input schema definition using Zod for validating the get-customer-orders tool parameters. Requires a numeric customerId string and has an optional limit parameter defaulting to 10.

  const GetCustomerOrdersInputSchema = z.object({
    customerId: z.string().regex(/^\d+$/, "Customer ID must be numeric"),
    limit: z.number().default(10)
  });
  
  type GetCustomerOrdersInput = z.infer<typeof GetCustomerOrdersInputSchema>;

• src/tools/getCustomerOrders.ts:16-24 (handler)

  Tool object definition containing the name, description, schema reference, and initialize method for setting up the GraphQL client dependency.

  const getCustomerOrders = {
    name: "get-customer-orders",
    description: "Get orders for a specific customer",
    schema: GetCustomerOrdersInputSchema,
  
    // Add initialize method to set up the GraphQL client
    initialize(client: GraphQLClient) {
      shopifyClient = client;
    },

• src/index.ts:202-217 (registration)

  MCP server tool registration for get-customer-orders. Defines the input schema (customerId as numeric string and limit), and provides the handler that calls getCustomerOrders.execute and returns JSON results.

  server.tool(
    "get-customer-orders",
    {
      customerId: z
        .string()
        .regex(/^\d+$/, "Customer ID must be numeric")
        .describe("Shopify customer ID, numeric excluding gid prefix"),
      limit: z.number().default(10)
    },
    async (args) => {
      const result = await getCustomerOrders.execute(args);
      return {
        content: [{ type: "text", text: JSON.stringify(result) }]
      };
    }
  );

• src/index.ts:69-69 (registration)

  Tool initialization where the Shopify GraphQL client is passed to getCustomerOrders to enable API communication.

  getCustomerOrders.initialize(shopifyClient);