Content
# 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
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:
```bash
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
