Shopify Storefront Server

This server provides access to the Shopify Storefront API via MCP, allowing AI assistants to query and interact with your Shopify store data.

Features

• Access to product, collection, and inventory data
• Cart creation and management
• Support for GraphQL queries and mutations
• Automatic token handling and validation
• Easy integration with MCP-compatible AI assistants

Setup Instructions

1. Clone this repository
2. Install dependencies: pip install -r requirements.txt
3. Copy .env.example to .env and configure your environment variables
4. Generate a Storefront API token via Shopify Admin (see below)
5. Run the server: python -m shopify_storefront_mcp_server

Environment Variables

Create a .env file using the provided .env.example as a template:

# Required
SHOPIFY_STOREFRONT_ACCESS_TOKEN=your_storefront_token
SHOPIFY_STORE_NAME=your-store-name

# Optional
SHOPIFY_API_VERSION=2025-04
SHOPIFY_BUYER_IP=127.0.0.1

Generating a Storefront API Token

1. Log in to your Shopify admin
2. Go to Apps and sales channels > Develop apps > Create an app
3. Name your app (e.g., "MCP Storefront")
4. Go to API credentials > Configure Storefront API scopes
5. Select necessary scopes:
   • unauthenticated_read_product_listings
   • unauthenticated_read_product_inventory
   • unauthenticated_read_product_pricing
   • unauthenticated_write_checkouts
   • unauthenticated_read_content
6. Save and copy the generated Storefront API access token
7. Add the token to your .env file as SHOPIFY_STOREFRONT_ACCESS_TOKEN

Usage Examples

Running with the MCP server:

python -m shopify_storefront_mcp_server

The server exposes the following MCP tools:

• shopify_discover: Detect if a URL belongs to a Shopify storefront and discover authentication tokens
• shopify_storefront_graphql: Execute GraphQL queries against the Storefront API
• customer_data: Unified tool for all customer data operations (Create, Read, Update, Delete)

Customer Resources

This server also provides MCP resources for customer information:

• customer://name: Customer's full name
• customer://email: Customer's email address
• customer://phone: Customer's phone number
• customer://shipping_address: Customer's shipping address (including address1, address2, city, state, postal_code, country)
• customer://billing_address: Customer's billing address (including address1, address2, city, state, postal_code, country)
• customer://profile: Complete customer profile

Customer data is stored in user_data/customer.json and should be managed using the customer_data tool.

Managing Customer Data

The server provides a unified customer_data tool for managing all customer information. This tool consolidates create, read, update, and delete operations into a single interface.

Examples:

# Get all customer data
customer_data(operation="get")

# Get a specific field
customer_data(operation="get", field="name")
customer_data(operation="get", field="shipping_address")

# Update a specific field
customer_data(operation="update", field="name", value="Jane Doe")
customer_data(
    operation="update",
    shipping_address={
        "address1": "123 Main St",
        "address2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
    }
)

# Add custom fields
customer_data(
    operation="update",
    custom_fields={
        "preferences": {
            "theme": "dark",
            "notifications": "email",
            "language": "en-US"
        },
        "loyalty_tier": "gold",
        "last_purchase_date": "2023-06-15"
    }
)

# Get a custom field
customer_data(operation="get", field="preferences")
customer_data(operation="get", field="loyalty_tier")

# Update single custom field
customer_data(operation="update", field="loyalty_tier", value="platinum")

# Delete a specific field
customer_data(operation="delete", field="phone")
customer_data(operation="delete", field="preferences")

# Delete all customer data
customer_data(operation="delete")

This consolidated tool simplifies integration with AI assistants by providing a consistent interface for all customer data operations, including both standard customer information and any custom fields that may be useful for personalization.

Data Privacy & Storage

Customer data is stored in user_data/customer.json. This file contains personal information and should not be committed to version control. The repository includes:

• user_data/customer.json.example: A template file showing the expected structure with dummy data
• Entries in .gitignore to prevent accidental commits of actual customer data

When deploying this server, the user_data/customer.json file will be created automatically when the customer_data tool is first used. You can also copy and rename the example file to get started:

cp user_data/customer.json.example user_data/customer.json

All data stored in the customer file persists between server restarts. The file supports both standard customer fields (name, email, addresses) and arbitrary custom fields for AI personalization.

Creating Checkouts with Customer Data

The server makes it easy to create Shopify checkouts that include customer information by combining the customer_data and shopify_storefront_graphql tools.

Example workflow:

# Step 1: Get customer data
customer_profile = customer_data(operation="get")

# Step 2: Create a cart with GraphQL
cart_mutation = """
mutation createCart($lines: [CartLineInput!]!) {
  cartCreate(input: {lines: $lines}) {
    cart {
      id
      checkoutUrl
    }
    userErrors {
      field
      message
    }
  }
}
"""

cart_variables = {
  "lines": [
    {
      "merchandiseId": "gid://shopify/ProductVariant/12345678901234",
      "quantity": 1
    }
  ]
}

cart_result = shopify_storefront_graphql(
  mode="execute",
  host="your-store.myshopify.com",
  token="your_storefront_token",
  query=cart_mutation,
  variables=cart_variables
)

# Step 3: Apply customer attributes to the cart
cart_id = # extract from cart_result
customer_info = json.loads(customer_profile)

attributes_mutation = """
mutation updateCartAttributes($cartId: ID!, $attributes: [AttributeInput!]!) {
  cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
    cart {
      id
      checkoutUrl
    }
    userErrors {
      field
      message
    }
  }
}
"""

attributes_variables = {
  "cartId": cart_id,
  "attributes": [
    {
      "key": "email",
      "value": customer_info["email"]
    },
    {
      "key": "deliveryAddress",
      "value": json.dumps(customer_info["shipping_address"])
    }
  ]
}

shopify_storefront_graphql(
  mode="execute",
  host="your-store.myshopify.com",
  token="your_storefront_token",
  query=attributes_mutation,
  variables=attributes_variables
)

This approach gives you complete control over the checkout process while leveraging the stored customer information.

Troubleshooting

If you encounter authentication errors:

1. Verify token format: Storefront API tokens should start with shpsa_ (newer) or shpat_ (older)
2. Check store name: Ensure SHOPIFY_STORE_NAME is correct (without .myshopify.com)
3. Check API version: Make sure the API version is supported
4. Test token: Use cURL to test your token directly:

   curl -X POST \
     https://your-store.myshopify.com/api/2025-04/graphql.json \
     -H "Content-Type: application/json" \
     -H "X-Shopify-Storefront-Access-Token: your_token" \
     -d '{"query": "query { shop { name } }"}'
   

5. Regenerate token: If issues persist, create a new token with proper scopes

Security Considerations

• Never commit your .env file or any files containing API tokens
• Use environment variables for all sensitive information
• Consider setting up IP restrictions in your Shopify Admin
• Review the permissions granted to your Storefront API token