Shopify MCP Server

Implementation Reference

• src/tools/getCustomers.ts:26-109 (handler)

  The execute function that implements the core logic for fetching customers from Shopify GraphQL API. It handles the query construction, executes the GraphQL request, parses the response, and formats the customer data with details like name, email, phone, addresses, amount spent, and order count.

  execute: async (input: GetCustomersInput) => {
    try {
      const { searchQuery, limit } = input;
  
      const query = gql`
        query GetCustomers($first: Int!, $query: String) {
          customers(first: $first, query: $query) {
            edges {
              node {
                id
                firstName
                lastName
                email
                phone
                createdAt
                updatedAt
                tags
                defaultAddress {
                  address1
                  address2
                  city
                  provinceCode
                  zip
                  country
                  phone
                }
                addresses {
                  address1
                  address2
                  city
                  provinceCode
                  zip
                  country
                  phone
                }
                amountSpent {
                  amount
                  currencyCode
                }
                numberOfOrders
              }
            }
          }
        }
      `;
  
      const variables = {
        first: limit,
        query: searchQuery
      };
  
      const data = (await shopifyClient.request(query, variables)) as {
        customers: any;
      };
  
      // Extract and format customer data
      const customers = data.customers.edges.map((edge: any) => {
        const customer = edge.node;
  
        return {
          id: customer.id,
          firstName: customer.firstName,
          lastName: customer.lastName,
          email: customer.email,
          phone: customer.phone,
          createdAt: customer.createdAt,
          updatedAt: customer.updatedAt,
          tags: customer.tags,
          defaultAddress: customer.defaultAddress,
          addresses: customer.addresses,
          amountSpent: customer.amountSpent,
          numberOfOrders: customer.numberOfOrders
        };
      });
  
      return { customers };
    } catch (error) {
      console.error("Error fetching customers:", error);
      throw new Error(
        `Failed to fetch customers: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }

• src/tools/getCustomers.ts:6-9 (schema)

  Input schema definition using Zod that validates the tool's input parameters: searchQuery (optional string for filtering by name/email) and limit (number with default value of 10).

  const GetCustomersInputSchema = z.object({
    searchQuery: z.string().optional(),
    limit: z.number().default(10)
  });

• src/tools/getCustomers.ts:16-24 (schema)

  Tool definition object containing the tool name ('get-customers'), description, schema reference, and initialize method that sets up the GraphQL client dependency.

  const getCustomers = {
    name: "get-customers",
    description: "Get customers or search by name/email",
    schema: GetCustomersInputSchema,
  
    // Add initialize method to set up the GraphQL client
    initialize(client: GraphQLClient) {
      shopifyClient = client;
    },

• src/index.ts:109-121 (registration)

  Registration of the 'get-customers' tool with the MCP server using server.tool(), defining the input schema with searchQuery and limit parameters, and wiring up the execute handler to return JSON-formatted results.

  server.tool(
    "get-customers",
    {
      searchQuery: z.string().optional(),
      limit: z.number().default(10)
    },
    async (args) => {
      const result = await getCustomers.execute(args);
      return {
        content: [{ type: "text", text: JSON.stringify(result) }]
      };
    }
  );

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

  Initialization call that injects the configured Shopify GraphQL client into the getCustomers tool before registration.

  getCustomers.initialize(shopifyClient);