Shopify MCP Server

Implementation Reference

• src/tools/getOrders.ts:26-178 (handler)

  The execute function contains the main handler logic for get-orders tool. It validates input, builds GraphQL query based on status filter, fetches orders from Shopify API, formats the response including order details, customer info, and line items.

  execute: async (input: GetOrdersInput) => {
    try {
      const { status, limit } = input;
  
      // Build query filters
      let queryFilter = "";
      if (status !== "any") {
        queryFilter = `status:${status}`;
      }
  
      const query = gql`
        query GetOrders($first: Int!, $query: String) {
          orders(first: $first, query: $query) {
            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
                }
                shippingAddress {
                  address1
                  address2
                  city
                  provinceCode
                  zip
                  country
                  phone
                }
                lineItems(first: 10) {
                  edges {
                    node {
                      id
                      title
                      quantity
                      originalTotalSet {
                        shopMoney {
                          amount
                          currencyCode
                        }
                      }
                      variant {
                        id
                        title
                        sku
                      }
                    }
                  }
                }
                tags
                note
              }
            }
          }
        }
      `;
  
      const variables = {
        first: limit,
        query: queryFilter || undefined
      };
  
      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,
          shippingAddress: order.shippingAddress,
          lineItems,
          tags: order.tags,
          note: order.note
        };
      });
  
      return { orders };
    } catch (error) {
      console.error("Error fetching orders:", error);
      throw new Error(
        `Failed to fetch orders: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }

• src/tools/getOrders.ts:5-11 (schema)

  Input schema definition using Zod for validating get-orders parameters. Accepts status (enum: any/open/closed/cancelled, default: any) and limit (number, default: 10).

  // Input schema for getOrders
  const GetOrdersInputSchema = z.object({
    status: z.enum(["any", "open", "closed", "cancelled"]).default("any"),
    limit: z.number().default(10)
  });
  
  type GetOrdersInput = z.infer<typeof GetOrdersInputSchema>;

• src/index.ts:123-135 (registration)

  MCP server tool registration for get-orders. Registers the tool with its schema and wraps the execute function to return properly formatted JSON response.

  server.tool(
    "get-orders",
    {
      status: z.enum(["any", "open", "closed", "cancelled"]).default("any"),
      limit: z.number().default(10)
    },
    async (args) => {
      const result = await getOrders.execute(args);
      return {
        content: [{ type: "text", text: JSON.stringify(result) }]
      };
    }
  );

• src/tools/getOrders.ts:16-24 (helper)

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

  const getOrders = {
    name: "get-orders",
    description: "Get orders with optional filtering by status",
    schema: GetOrdersInputSchema,
  
    // Add initialize method to set up the GraphQL client
    initialize(client: GraphQLClient) {
      shopifyClient = client;
    },

• src/index.ts:66-66 (helper)

  Initialization of getOrders tool with the Shopify GraphQL client before tool registration.

  getOrders.initialize(shopifyClient);