Shopify Storefront MCP 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

Clone this repository
Install dependencies: pip install -r requirements.txt
Copy .env.example to .env and configure your environment variables
Generate a Storefront API token via Shopify Admin (see below)
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

Log in to your Shopify admin
Go to Apps and sales channels > Develop apps > Create an app
Name your app (e.g., "MCP Storefront")
Go to API credentials > Configure Storefront API scopes
Select necessary scopes:

unauthenticated_read_product_listings
unauthenticated_read_product_inventory
unauthenticated_read_product_pricing
unauthenticated_write_checkouts
unauthenticated_read_content

Save and copy the generated Storefront API access token
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:

Verify token format: Storefront API tokens should start with shpsa_ (newer) or shpat_ (older)
Check store name: Ensure SHOPIFY_STORE_NAME is correct (without .myshopify.com)
Check API version: Make sure the API version is supported
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 } }"}'

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

shopify-storefront-mcp-server